Arviz: Add better documentation for how to build hosted documentation

[canyon289]

Copying from another issue ticket, we can improve our static documentation for how to build our generated documentation

The only thing that might be more helpful is updating the instructions a bit under Building documentation with Docker to let contributors know they have to rebuild with the --docs command after changes and the index.html file has to be dragged and dropped into the browser.

_Originally posted by @ari-hacks in https://github.com/arviz-devs/arviz/issues/1155#issuecomment-662350572_

[OriolAbril]

Also instrucctions on building docs locally can be improved.

[collinsuzebu]

If this issue haven't been taken, I'd like to resolve it.

[canyon289]

Not taken! Please go ahead

[canyon289]

@collinsuzebu Any interest? If not I'll remove your assignment to this issue so someone else can work on it

[collinsuzebu]

@canyon289 apologies for the delay in getting this done. I was unable to get the project running on my windows machine. My initial intention was to set it up once my Linux machine is restored by following @ari-hacks steps and properly documenting the sections that were not clear. I'm still interested in fixing this issue. Would it be advisable to get it done without first running the project locally?

[ari-hacks]

Hey @collinsuzebu , are you still interested in taking this on? I can tackle it if you are unavailable.

The only thing that might be more helpful is updating the instructions a bit under Building documentation with Docker to let contributors know they have to rebuild with the --docs command after changes and the index.html file has to be dragged and dropped into the browser.

Under building docs I would just make a note about the changes listed above.

[canyon289]

@ari-hacks its yours.

@collinsuzebu Apologies I missed your original message

[ahartikainen]

If user add [docs] to PR title, then CI will build and upload the docs, which can be downloaded to user computer.

It can be found under artifacts in the main CI page (it looks like "Published n")

e.g. https://dev.azure.com/ArviZ/ArviZ/_build/results?buildId=3560&view=results <-- this CI run did not create docs

[ari-hacks]

If user add [docs] to PR title, then CI will build and upload the docs, which can be downloaded to user computer.

It can be found under artifacts in the main CI page (it looks like "Published n")

e.g. https://dev.azure.com/ArviZ/ArviZ/_build/results?buildId=3560&view=results <-- this CI run did not create docs

Hey, @ahartikainen should this be a separate issue?

[ahartikainen]

I think it is already documented. I just wanted to share the info, so you are aware of this.

[ari-hacks]

@canyon289 and @ahartikainen I've made this update but I'm also unable to build the docs (nothing generates under docs/build dir). The above CI run indicates a possible linting issue?

When I attempt to build this is the error I'm getting:

[ahartikainen]

Interesting, maybe there is a problem with sharing your local folder.

[OriolAbril]

Maybe its due to the doc reorganizations :thinking: I'll check

[OriolAbril]

Maybe its due to the doc reorganizations thinking I'll check

Indeed, https://github.com/arviz-devs/arviz/blob/master/scripts/container.sh#L38 should be:

"if [ -d ./doc/build ]; then python -msphinx -M clean doc/source doc/build; fi && sphinx-build doc/source doc/build -b html"

The conf.py file used to be on doc/ but was moved to doc/source so now it's not found anymore by the script because it's still looking at the old location.

Azure CI script was updated https://github.com/arviz-devs/arviz/blob/master/.azure-pipelines/azure-pipelines-docs.yml#L60-L61 and can serve as an example to compare against when things don't work

[ari-hacks]

@OriolAbril - ah I see , thanks! Should I go ahead and update that line with this PR or should that be a separate issue?

[OriolAbril]

I think we can do it in the same PR, but I don't have strong preferences on this