Problem with referencing of pages in documentation

[tlienart]

This part in particular:

### Examples

The following examples will introduce you to the functionalities of the package.
The code to all examples can be found in the [examples directory](https://github.com/alan-turing-institute/PDMP.jl/tree/master/example).

```@contents
Pages = ["examples/bps_mvg_constr.md", "examples/lbps_gchain.md"]
Depth = 2
x```

(x is not present, it's just to escape the triple quote). This does not work.

It's converted to

<p>The following examples will introduce you to the functionalities of the package.
The code to all examples can be found in the <a href="https://github.com/alan-turing-institute/PDMP.jl/tree/master/example">examples directory</a>.</p>
<p>```@contents
Pages = ["examples/bps_mvg_constr.md", "examples/lbps_gchain.md"]
Depth = 2</p>
<pre class="codehilite"><code>### Code documentation

however, locally, the docs/build/index.md contains

- [Truncated Multivariate Gaussian](examples/bps_mvg_constr.md#Truncated-Multivariate-Gaussian-1)
- [Chain of Multivariate Gaussian](examples/lbps_gchain.md#Chain-of-Multivariate-Gaussian-1)

which should be appropriately converted.

@martintoreilly could you look into this?

[tlienart]

I was trying to follow this: https://github.com/JuliaDiffEq/DiffEqDocs.jl but to no avail unfortunately

[tlienart]

https://github.com/dmlc/MXNet.jl seems to also use that pipeline, maybe good for inspiration

[martintoreilly]

The issue may potentially be with the value of docs_dir in docs/mkdocs.yaml. This was originally build and was changed to src in commit bcdb16b. This may potentially be causing deploydocs to pick up the unprocessed markdown in docs/src, rather than the processed markdown in docs/src/build that has had the @content blocks replaced with link lists.

Set docs_dir: 'src/build' in commit 13a5332 to see if this fixes things.

Edit: Travis and Appveyor builds passed, but no autodocs commit was made to gh-pages Edit: Travis build log shows Documenter aborted with the following error Config value: 'docs_dir'. Error: The path src/build doesn't exist

[martintoreilly]

Documenter examples set docs_dir: 'build' (e.g. here). Did this in commit 6ddc968 to see if this fixes things.

Edit: Fixed by commit 6ddc968.

[tlienart]

@martintoreilly I was checking the doc this morning and it seems the references are still not working. I tried to modify a few things but to no avail. The links highlighted below should lead to pages and don't (lead to 404).

https://alan-turing-institute.github.io/PDMP.jl/latest/

[tlienart]

I'll try to follow this https://maurow.bitbucket.io/notes/documenting-a-julia-package.html

[tlienart]

After a lot of random attempts, it now works following recommended :html syntax and removing yml file as in https://github.com/JuliaDocs/Documenter.jl/blob/master/docs/make.jl .

Using DOCUMENTER_DEBUG set to True in travis environment variable allows for more informed debugging of the documenting process.