sphinx-doc / sphinx-doc/sphinx

sphinx_build: index.rst changes should force rebuilding every html file

Open
#5,506 4 comments 9 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

builder:html internals:toctree type:bug
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
  1. Complete a successful sphinx-build.
  2. Move the license entry before the credits entry in index.rst.
  3. Repeat sphinx-build
Results

Files other than index.html show the incorrect (original) order rather than the changed order:

image

Expected results

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

image

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.