Sphinx: Issue when rebuilding the docs
I can't rebuild my docs. Once the docs are built, and I make changes to my source files the generated HTML will not update.
I have some warnings in the output but no errors. I can't seam to find out what Im doing wrong.
bash-4.3$ make html
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.4.8
WARNING: while setting up extension sensio.sphinx.codeblock: directive 'code-block' is already registered, it will be overridden
WARNING: while setting up extension sensio.sphinx.codeblock: directive 'sourcecode' is already registered, it will be overridden
Initializing Spelling Checker
loading pickled environment... done
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
/doc/index.rst:18: WARNING: toctree contains reference to nonexisting document u'Introduction/asynchronous-example'
/doc/index.rst:41: WARNING: toctree glob pattern u'MessageBus/*' didn't match any documents
/doc/index.rst:48: WARNING: Explicit markup ends without a blank line; unexpected unindent.
looking for now-outdated files... none found
pickling environment... done
checking consistency... /doc/Guides/asynchronous-example.rst:: WARNING: document isn't included in any toctree
/doc/Guides/command_bus.rst:: WARNING: document isn't included in any toctree
/doc/Guides/event_bus.rst:: WARNING: document isn't included in any toctree
/doc/Guides/message_recorder.rst:: WARNING: document isn't included in any toctree
/doc/upgrade_guide.rst:: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] index
generating indices... genindex
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, 10 warnings.
Build finished. The HTML pages are in _build/html.
Nyholm
All 26 comments
Try deleting your _build directory and other generated files.
SylvainCorlay
on 9 Dec 2016
Thank you for your suggestion. But Im afraid it does not help. Which makes this extra weird.
Nyholm
on 9 Dec 2016
Is there a _generate directory in your source?
SylvainCorlay
on 9 Dec 2016
No only a _build.
Nyholm
on 9 Dec 2016
You may have a stable version of the package installed that is being picked
up.
On Dec 9, 2016 7:47 PM, "Tobias Nyholm" notifications@github.com wrote:
No only a _build.
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/sphinx-doc/sphinx/issues/3213#issuecomment-266090263,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ACSXFgGVCZ1tnlKwzwL3YoGFHT4dEPltks5rGaI4gaJpZM4LJCEM
.
SylvainCorlay
on 9 Dec 2016
What do you mean?
Nyholm
on 9 Dec 2016
I can't rebuild my docs. Once the docs are built, and I make changes to my source files the generated HTML will not update.
What did you mean "rebuild"?
Please tell me your operations in detail.
What message did you see on failed to rebuild?
tk0miya
on 10 Dec 2016
Sure. I check out a documentation project that are using Shinx. It does not matter which, I've tried 3 different ones. Then I run make html
% docker run --rm -it -v "$PWD":/doc webplates/readthedocs 2 ↵
bash-4.3$ make html
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.4.8
making output directory...
Initializing Spelling Checker
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 49 source files that are out of date
updating environment: 49 added, 0 changed, 0 removed
reading sources... [100%] plugins/stopwatch
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] plugins/stopwatch
generating indices... genindex
writing additional pages... search
copying images... [100%] assets/img/symfony-profiler/request-stack.png
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.
Build finished. The HTML pages are in _build/html.
In my _build folder I get all the HTML and it looks great. Then I decide to make a change. So I edit a file and run make html again.
bash-4.3$ make html
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.4.8
Initializing Spelling Checker
loading pickled environment... done
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
/doc/index.rst:140: WARNING: Explicit markup ends without a blank line; unexpected unindent.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying images... [100%] assets/img/plugefant.png
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 1 warning.
Build finished. The HTML pages are in _build/html.
But my HTML has not changed. I can see the line saying updating environment: 0 added, 1 changed, 0 removed which looks okey.
If I remove my _build folder now and run make html
bash-4.3$ make html
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.4.8
making output directory...
Initializing Spelling Checker
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 49 source files that are out of date
updating environment: 49 added, 0 changed, 0 removed
reading sources... [100%] plugins/stopwatch
/doc/index.rst:140: WARNING: Explicit markup ends without a blank line; unexpected unindent.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] plugins/stopwatch
generating indices... genindex
writing additional pages... search
copying images... [100%] assets/img/symfony-profiler/request-stack.png
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 1 warning.
Build finished. The HTML pages are in _build/html.
... I still do not see my change.
The project I checkout in this example was https://github.com/php-http/documentation
But I get the same issues with other projects.
Nyholm
on 11 Dec 2016
Strange.. I guess..
- rst file you changed is not a part of the project (or not saved)
or - current directory in docker environment is not
/docdirectory which is mounted as volume of host
shimizukawa
on 11 Dec 2016
Thank you for getting back to me.
It is a part of the project and it is properly saved. Edit the file and do
touchgives the same result.It is a docker image... Im starting to hesitate here. See https://github.com/webplates/docker-readthedocs/blob/master/Dockerfile
My working dir and volume is /doc. I start the docker image with docker run --rm -it -v "$PWD":/doc webplates/readthedocs
Nyholm
on 11 Dec 2016
I tried with same docker image, same target project, and same procedure, however I can't reproduce it.
C:\Project\sphinx-dev\sphinx>docker run -it --rm -v C:/Project/sphinx-dev/issues/php-http-documentation:/doc webplates/readthedocs
bash-4.3$ ls
CONTRIBUTING Makefile _static clients components development favicon.ico image-sources integrations message.rst requirements.txt watch.sh
LICENSE README.md assets clients.rst conf.py discovery.rst httplug index.rst message plugins spelling_word_list.txt
bash-4.3$ make html
make: Warning: File 'Makefile' has modification time 340602 s in the future
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.4.8
making output directory...
Initializing Spelling Checker
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 49 source files that are out of date
updating environment: 49 added, 0 changed, 0 removed
reading sources... [100%] plugins/stopwatch
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] plugins/stopwatch
generating indices... genindex
writing additional pages... search
copying images... [100%] assets/img/symfony-profiler/request-stack.png
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.
Build finished. The HTML pages are in _build/html.
make: warning: Clock skew detected. Your build may be incomplete.
bash-4.3$ make html
make: Warning: File 'Makefile' has modification time 340581 s in the future
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.4.8
Initializing Spelling Checker
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
build succeeded.
Build finished. The HTML pages are in _build/html.
make: warning: Clock skew detected. Your build may be incomplete.
Here I modified index.rst as: PHP-HTTP to PHP-HTTP2
bash-4.3$ make html
make: Warning: File 'Makefile' has modification time 340553 s in the future
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.4.8
Initializing Spelling Checker
loading pickled environment... done
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
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying images... [100%] assets/img/plugefant.png
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.
Build finished. The HTML pages are in _build/html.
make: warning: Clock skew detected. Your build may be incomplete.
Finally I got a updated index.html file that contains modified part (PHP-HTTP2).
shimizukawa
on 11 Dec 2016
So, Any guesses what I mess up with my environment?
Nyholm
on 11 Dec 2016
Ping @sagikazarmark. Can you make a guess?
Nyholm
on 11 Dec 2016
I also tried to reproduce on Linux and Mac and I don't experience this problem. I am especially confused because in Docker it should be the same environment. Maybe something messed up with your hard drive? Filesystem, messed up mtimes, etc.
sagikazarmark
on 12 Dec 2016
If you have a version of the package installed with --user that could be the reason.
SylvainCorlay
on 12 Dec 2016
It's a docker image, the installation can be found here: https://github.com/webplates/docker-readthedocs/blob/master/Dockerfile
sagikazarmark
on 12 Dec 2016
Is this really a issue of Sphinx? I feel this is an environment issue of docker.
tk0miya
on 12 Dec 2016
Maybe it is an issue with my Docker setup or the Docker image or maybe it is Sphinx. But can you explain it? Or can you tell for sure since none of us have any idea what causes the error..
Nyholm
on 12 Dec 2016
@Nyholm Does it work without docker?
sagikazarmark
on 12 Dec 2016
No, it does not. :(
Without docker:
If Im not using docker I had the issue on OSX with six. I think I solved it by installing six by installing Sphinx with pip install -U Sphinx --user
But I've run into another issue. (Think it is same as this)
[tobias@Tobias-MBP:~/Workspace/PHPStorm/php-http-documentation on master]
% make html
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.5
Extension error:
Could not import extension sphinx.builders.linkcheck (exception: No module named html_parser)
make: *** [html] Error 1
Try installing pyenv, install python 3 into your user prefix, install whatever you need there.
sagikazarmark
on 12 Dec 2016
Im not too sure what caused this but it seams to be fixed now.
What I did:
1) Reinstalled docker for Mac. (Did not copy any thing from previous installation)
2) Downloaded the a new version of the https://github.com/webplates/docker-readthedocs/blob/master/Dockerfile that @sagikazarmark updated a few days ago
Now it works like a charm! Im very satisfied. =)
Thank you all for the support and the answers.
Nyholm
on 17 Dec 2016
For the record: the change I did in the docker container was related to permission handling in cases when the container ran in non-interactive mode (only building). However, according to @Nyholm's reports, the issue persisted even in interactive mode. I suspect that something wrong was going on with the docker filesystem.
sagikazarmark
on 18 Dec 2016
I am getting this same problem, Win10, VSCode, F:FusionSource_buildhtml
I added one doc yesterday, built it, and it worked fine. After doing some work on it, saving it, and rebuilding the HTML files (make) I find the page won't rebuild. I've deleted it from the build folder and on build nothing re-appears. Most frustrating.
wilfy50
on 31 Jul 2018
I wanted to test my local changes, so I have to replace to corresponding file in Python path with the changed file.
The takeaway is sphinx-doc does generates doc from Python path instead of local directory (e.g., git repo).
Note: I did not use docker.
helinwang
on 19 Nov 2019
I had similar issue. But later found out I was updating the wrong rst file. The index.rst file inside of the bin folder is the one you should modify or create more rst file. Also make sure you virtual env is activated otherwise make html might not work. I hope this helps someone.
gconnect
on 15 Jun 2020
Related issues
tuomas2
·
3Comments
shimizukawa
·
3Comments
ewjoachim
·
3Comments
dvorapa
·
3Comments
miketheman
·
3Comments