sphinx-doc / sphinx-doc/sphinx
sphinx_build: index.rst changes should force rebuilding every html file
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Problem
index.rst changes should force rebuilding every html file since the short table of contents is included in every html, but the incremental sphinx-build doesn't check this dependency. (Hope this is enough detail since I'm not the one who set up sphinx for my project; I'm just trying to write documentation today.)
Procedure to reproduce the problem
original index.rst is (in part):
.. toctree::
:caption: Preamble
self
introduction
credits
license
- Complete a successful
sphinx-build. - Move the
licenseentry before thecreditsentry inindex.rst. - Repeat
sphinx-build
Results
Files other than index.html show the incorrect (original) order rather than the changed order:

Expected results
All html files should show the correct (changed) order, which only appears in index.html:

Error logs
COQBIN="/cygdrive/c/Users/Jim.DESKTOP-MMPNVGH/Documents/coqSource/coq/bin/" sphinx-build -b html \
-d doc/sphinx/_build/doctrees -j4 doc/sphinx doc/sphinx/_build/html
Running Sphinx v1.7.7
loading pickled environment... done
Skipping /cygdrive/c/Users/Jim.DESKTOP-MMPNVGH/Documents/coqSource/coq/doc/sphinx/credits.html.rst: /cygdrive/c/Users/Jim.DESKTOP-MMPNVGH/Documents/coqSource/coq/doc/sphinx/credits.rst is up to date
Copying /cygdrive/c/Users/Jim.DESKTOP-MMPNVGH/Documents/coqSource/coq/doc/sphinx/index.html.rst to /cygdrive/c/Users/Jim.DESKTOP-MMPNVGH/Documents/coqSource/coq/doc/sphinx/index.rst
Skipping /cygdrive/c/Users/Jim.DESKTOP-MMPNVGH/Documents/coqSource/coq/doc/sphinx/zebibliography.html.rst: /cygdrive/c/Users/Jim.DESKTOP-MMPNVGH/Documents/coqSource/coq/doc/sphinx/zebibliography.rst is up to date
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
waiting for workers...
generating indices... genindex coq-cmdindex coq-tacindex coq-optindex coq-exnindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.
Environment info
- OS: Windows
- Python version: 3.6.5
- Sphinx version: 1.7.7
- <Extra tools e.g.: Browser, tex or something else>
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the issue with the shown index.rst toctree and incremental sphinx-build command on Sphinx 1.7.7. Trace how the changed index.rst is recorded and how dependent HTML documents are selected for rebuilding. Done means reordering entries causes every affected HTML file to show the new table-of-contents order.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- build-system, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100