[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.

[MatthewMiddlehurst]

Did you run pip install --editable .[docs] or just pip install .[docs]?

[MatthewMiddlehurst]

@IRKnyazev @Cyril-Meyer @aadya940 If you find some time to test the above (replace batch file with makefile if possible) that would be helpful. Mention if you installed with --editable or not, as that may be the issue.

[Cyril-Meyer]

Did you run pip install --editable .[docs] or just pip install .[docs]?

I'm not sure, but knowing myself, I copied and pasted lines from the documentation, so, my setup is probably the following :

pip install --editable .[dev]
pip install tensorflow # want to avoid all_extra but also want to work on DL modules
pre-commit install
pip install .[docs]

(Win10 Python 3.10.11)

@IRKnyazev @Cyril-Meyer @aadya940 If you find some time to test the above (replace batch file with makefile if possible) that would be helpful. Mention if you installed with --editable or not, as that may be the issue.

I just tested again right now, with cmd and git bash (but neither use the makefile).

• make html : does not update the docstring
• sphinx-apidoc -o docs/ ../ : does not update the docstring
• make html again : does not update the docstring

I do all my test on the branch I identified the problem (#1892), so I can check if the arsenal ref is changed with the new one.

After all of this, I checked things manually. My python file is good with new docstring.
aeon.classification.convolution_based.Arsenal.doctree in aeon\docs\_build\doctrees\api_reference\auto_generated and the file is not good (not with the new docstring ref).
I've tried to delete aeon.classification.convolution_based.Arsenal.doctree but it still not work.

python -m http.server

Again, I don't understand why this, you can just open the index.html file in any browser.

[MatthewMiddlehurst]

yeah python -m http.server was not needed. But that just leaves it at:

1. pip install --editable .[docs]
2. cd docs/
3. make.bat html

I again had no issue running step 3 to update the autogenerated api file and it changed after refreshing.

Could you maybe take a look as someone not trapped on Windows @chrisholder 🙂.

[MatthewMiddlehurst]

#2297 updates the documentation for the above among other things. Hopefully Chris can give it a troubleshoot for other OS.

[chrisholder]

I can recreate this on both linux (Ubuntu 22.04) and macos (Sequoia 15.0.1). Same issue - when I update the docstrings the documentation website does not update. The only way to make it update is to rebuild the entire docs.

[MatthewMiddlehurst]

Could you expand on what you mean by rebuild the entire docs? Weird that make.bat/Windows works but Makefile/Unix does not.

[chrisholder]

I mean re-running the following:

cd docs/
make html
python -m http.server

If I change anything in the docs, to update it on the local website I have to stop the server and rerun the above commands.

[MatthewMiddlehurst]

That is expected, do you need to run the server though or can you just open the html doc in a browser and update it using make?

[chrisholder]

Spoke to matt for clarity and the docs on linux and macos are working fine for me. I initially thought the conversation was about hot reloading the website as soon as you make a change.

On both linux and macos when I make a change to the docs and rerun make html the docs update correctly for me