4

I am having an issue where Sphinx won't update the html page when my python file is updated.

My docs folder look like this: enter image description here

The api.rst file in the folder above looks like this:

API Documentation
=================

This is a documentation for the Helstrom Quantum Centroid (HQC) classifier's API.

.. automodule:: hqc.HQC
    :members:

The hqc folder looks like this: enter image description here

Both the docs folder and the hqc folder are in the same HQC folder.

When I update the HQC.py file and run make html in the command prompt, the html page won't update itself.

But I noticed that when I change the folder name from hqc to a new folder name, say hqc1 (and change hqc.HQC to hqc1.HQC in the api.rst file too), then the html page updates when I run make html.

What am I missing or how do I fix this? Would really prefer the hqc folder name to stay as hqc.

mzjn
  • 48,958
  • 13
  • 128
  • 248
Leockl
  • 1,906
  • 5
  • 18
  • 51
  • 1
    `make clean && make html` should purge the build and rebuild docs. If you do not see updates that you expect, check your `conf.py` for the location of your build. Finally make sure that the package you want to document is in fact a Python package (contains an `__init__.py` file) and is included in your python in your `conf.py`. – Steve Piercy Jan 19 '20 at 08:27
  • Perhaps you already have HQC installed and Sphinx is extracting docstrings from that version instead of the clone that you are currently working on. You may need to add a `sys.path.insert` entry in conf.py. See https://stackoverflow.com/q/46264706/407651. – mzjn Jan 19 '20 at 12:12
  • Hi @mzjn, I have added `sys.path.insert` but it didn't work. But you had pointed to something @Steve Piercy had mentioned in your link which could be it. – Leockl Jan 19 '20 at 13:42
  • Hi @Steve Piercy (and @mzjn), according to this [link](https://stackoverflow.com/questions/46264706/updating-docstring-in-sphinx), you mentioned that "when you update a docstring, are you updating the copy that you cloned or the copy in the installed package? Sphinx will build docs from the latter. When you edit the cloned copy, you should reinstall the local edited copy.", do you mean if I have a copy installed in pip, I will need to update docstrings in this copy in pip first as Sphinx builds on docs in pip? – Leockl Jan 19 '20 at 13:47
  • Is this still a problem? I notice that you use `.. automodule:: hqc.HQC` in the question. On Github, you have `.. automodule:: HQC.HQC` (https://raw.githubusercontent.com/leockl/helstrom-quantum-centroid-classifier/master/docs/api.rst). – mzjn Jan 21 '20 at 06:11
  • Hi @mzjn, I couldn't find a solution to the problem, so I decided to rename the folder to HQC (rather than hqc which is still what prefer if there was a solution as I am unsure if this will have any downstream effect as when I uploaded my package into pip, I am still using a hqc folder rather than a HQC folder). Do you know where I might have gone wrong? – Leockl Jan 21 '20 at 14:04
  • You may find the [-a and -E](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-a) build flags handy when Sphinx isn't picking up source changes. – morric Aug 08 '21 at 19:49

4 Answers4

4

Happens sometimes when sphinx doesn't recognize the changes, use make clean && make html, this will first delete all existing files and then create new ones.

bluesummers
  • 11,365
  • 8
  • 72
  • 108
  • 2
    Thanks. I did what you suggested but it didn't work. Any other suggestions I could try and see? – Leockl Jan 19 '20 at 07:42
  • I am not entirely sure if this is connected, but I have been getting this warning message (which is not in red, just the usual grey): `writing additional pages... searchc:\users\hp\appdata\local\programs\python\python38-32\lib\site-packages\sphinx_rtd_theme\search.html:20: RemovedInSphinx30Warning: To modify script_files in the theme is deprecated. Please insert a – Leockl Jan 19 '20 at 07:56
  • If it helps, my `conf.py` file looks like the below: – Leockl Jan 19 '20 at 08:06
  • The "Options for HTML output" part – Leockl Jan 19 '20 at 08:09
  • # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. html_theme = 'sphinx_rtd_theme' # Add any paths that contain custom themes here, relative to this directory. html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # Add any paths that contain custom static files (such as style sheets) here, html_static_path = ['_static'] # Output file base name for HTML help builder. htmlhelp_basename = 'HQCdoc' – Leockl Jan 19 '20 at 08:09
  • if `make clean` followed by `make html` did not help, I really have no clue what's wrong – bluesummers Jan 19 '20 at 09:01
  • 1
    The RemovedInSphinx30Warning is probably not related to the main problem. See https://stackoverflow.com/a/57402446/407651. – mzjn Jan 19 '20 at 16:58
4

I was struggling with the same problem and, in my case, the issue was that sphinx was looking at an older version of my module installed locally.

Two things worked for me:

  1. Install my module with the -e flag:

pip install -e .

  1. Set the PYTHONPATH to point directly at my module when calling make:

PYTHONPATH=<path/to/your/module> make html

Fatore
  • 586
  • 8
  • 10
2

Well if you have a copy of your package installed then it'll always try to fetch the source code from the package which is installed and present in python\Lib folder. you can check if it's installed or not by running

pip list

So changing the code of your package which is present locally won't be helpful, so try to change the code of the package which is present in pythons lib folder instead.

sunil swain
  • 61
  • 2
0

If you try to reinstall sphinx into a new virtual environment (pyenv or conda) and rerun make clean html it should work. It did for me. Also make sure that you specify correctly the path to your python directory in conf.py. If conf.py is in docs and your python directory is located at the same level as docs then run: sys.path.insert(0, os.path.abspath('../'))

datamining1993
  • 1
  • 1