[DOC] Local documentation build

[Cyril-Meyer]

Describe the issue linked to the documentation

In documentation-build it is stated that :

1. To build the website locally, run:

cd docs
make html

It works, but "if it is docstring changes, you have to make sure all the API pages are being regenerated." (@MatthewMiddlehurst on slack in #help-desk)

As much as I know, I'm not the only one struggling with local build of documentation (e.g. to check if it works before PR), @IRKnyazev opened the discussion on slack and most of the current answer are "PR then check result".

Suggest a potential alternative/fix

There is a problem with those instructions, we need to correct them.

[TonyBagnall]

@aadya940 relevant to our discussion today

[aadya940]

Run the following command from project root Directory.

sphinx-apidoc -o docs/ .

Then run the other steps of make.
Then start an http server in the folder that contains the make build, that is, _build/html.

[IRKnyazev]

Run the following command from project root Directory.

sphinx-apidoc -o docs/ .

Then run the other steps of make.
Then start an http server in the folder that contains the make build, that is, _build/html.

I remember trying out the sphinx command yesterday but I didn't start a http server as you describe. Could you explain this step again, I don't really get what you mean?

[Cyril-Meyer]

Run the following command from project root Directory.

sphinx-apidoc -o docs/ .

Then run the other steps of make. Then start an http server in the folder that contains the make build, that is, _build/html.

Just tried to run this before make html but still does not work for me.
PR #1892 still do not appear correctly on local build but with older reference.

I remember trying out the sphinx command yesterday but I didn't start a http server as you describe. Could you explain this step again, I don't really get what you mean?

I don't think that is really required, as the static HTML can be directly opened in webbrowser.
If you really want to start an http server, you can use python -m http.server

[aadya940]

You'll have to delete the old files generated by the sphinx-apidoc if you've previously built the docs locally before. Anyways, I'll write a complete guide in a few days.

[aadya940]

Run the following command from project root Directory.

sphinx-apidoc -o docs/ .

Then run the other steps of make.
Then start an http server in the folder that contains the make build, that is, _build/html.

I remember trying out the sphinx command yesterday but I didn't start a http server as you describe. Could you explain this step again, I don't really get what you mean?

@IRKnyazev

python -m http.server

[aadya940]

@IRKnyazev @Cyril-Meyer For me, this #1905 works, you can try following the steps and let me know if you have issues. :))

[Cyril-Meyer]

@IRKnyazev @Cyril-Meyer For me, this #1905 works, you can try following the steps and let me know if you have issues. :))

@aadya940
Sorry, I won't be able to test before next week, but I'll take note and get back to you.
Anyway, what is the purpose of the http server ? Is there anything you can't do by just opening the index.html file ?

[IRKnyazev]

I still can't see my docstring changes locally :(
Here is exactly what I have done:
cd docs
make clean
sphinx-apidoc / -o .
.\make.bat html
cd _build/html
python -m http.server
Navigated to http://localhost:8000/ in browser.

Originally I would run make html and start index.html which didn't work either unfortunately.

[aadya940]

@IRKnyazev
If you're in the docs Directory, the apidoc command would be:

sphinx-apidoc -o ./ ../

[IRKnyazev]

Hi Aadya, still no luck.

[aadya940]

@IRKnyazev Yes, so the thing is , running only make clean wouldn't work. You'll have to also delete the old .rst files which were generated by sphinx-apidoc when you were building the docs earlier (Make sure you don't delete the `.rst files that were not autogenerated, I typically re-clone the project when building the docs again). The files to be deleted look like this:

After deleting these files, you'll have to run the sphinx-apidoc command again. Then make html and then run a http server in the _build/html directory.

Hope you get the point :))

[MatthewMiddlehurst]

I'll try to have a go at this today and see if I can get it to work 🙂

[MatthewMiddlehurst]

Hi everyone, this all worked fine for me only using make.bat on Windows for the most part, actually.

1. cd docs/
2. make.bat html
3. python -m http.server
4. http://localhost:8000/_build/html/ in browser

Examples are missing due to the messed up symlink, but everything else seems fine. Refreshing for docstring changes:

5. make.bat html
6. python -m http.server
7. Refresh the relevant html page in browser

It is definitely generating the relevant files and updating them on my end. No manually deleting files or running sphinx-apidoc.