python
Building docs without make doesn't seem to work
I followed https://devguide.python.org/documenting/#without-make to build the docs without make:
sphinx-build -bhtml . build/html
It finished without error but nothing showed up under build/
Wonder if it's just me. Perhaps I miss something? I've followed the previous steps and make html works for me (after blurb got installed).
On 2/4/2018 9:49 AM, Mariatta wrote:
I followed https://devguide.python.org/documenting/#without-make to build the docs without make:
|sphinx-build -bhtml . build/html |
It finished without error but nothing showed up under |build/|
Where are you running sphinx-build? My local repository has a build/ directory that consists of nothing but leftover test artifacts (which should probably be removed by the tests). That should not have html/.
I just ran the above (with a full path to sphinx-build) in /Doc, and /Doc/build/html was (still) populated with updated files, as expected. My sphinx install is probably a couple of years old, so that might possibly make a difference.
Hi @Mariatta
In a docker image based on the last ubuntu:rolling
docker run --rm -it ubuntu:rolling /bin/bash
apt-get update && apt-get install -y vim && vim /etc/apt/sources.list
# modify the repository to include the sources
apt-get update
apt-get install -y git-core python3-venv
apt-get build-dep -y python3
cd /tmp
git clone https://github.com/python/cpython
python3 -m venv /tmp/venv
source /tmp/venv/bin/activate
# we recommend to install sphinx and the dependencies
pip install wheel sphinx==1.6.1
cd cpython/Doc
# just build the documentation
sphinx-build -bhtml . build/html
# result is a build/html directory with the compiled documentation
so in my case, I have no issue with the documentation.
@Mariatta here is a small Dockerfile, you can read it https://gist.github.com/matrixise/a8d27af4c874da5fdc1d0b8cae5afccf maybe we could use it for the build of the documentation for the newcomers, but this one is not yet perfect.
it's just for the fun, I won't use it in production because I have no issue with the virtualenv system and Python in general. but normally with this Dockerfile, I just explain how I compile the documentation.
I think this devguide section should be restructured a bit to distinguish between building the HTML vs other formats and between Unix-y (make) vs Windows (make.bat) builds. I would expect that HTML builds on Unix is by the far the most common case and that's also the simplest:
cd Doc
make venv
make html
The docs should point out that building other formats (pdf, epub, etc) has more dependencies (LaTeX and friends) and is much more time consuming.
If it's possible to build all formats with make or make.bat, then why have a section about building without make? Keep it simple!
totally agree with you, but in this case, we could close this issue, and open a PR where we remove the build without make because that one would be useless.
@Mariatta For me too building in a venv with sphinxinstalled, using:
(cd Doc/; sphinx-build -b html . build/html)
works well. Have you tried running this at the root of cpython?
Next actions:
- Rename section "not make" to "using sphinx-build"
- Add a sentence or two on why using sphinx-build is useful in some cases e.g. using command line options such as verbosity, nit-picky, etc. http://www.sphinx-doc.org/en/master/man/sphinx-build.html#options
Likewise, I could build the docs just fine with python -b -X dev -m sphinx -n . _build/html.
If this issue should still be open, perhaps it could be retitled more appropriately, e.g. "Add brief non-make build invocation" or something like that.
For what its worth, even though I do have make on my system (as a Windows user), I nearly always build Sphinx docs with the full python -m sphinx instead of whatever particular make magic the individual project may be using, because it has consistent behavior between projects and platforms, avoids doing arbitrary things like creating venvs that may or may not work with my make, platform and (conda) environment, and ensures I am fully aware of, and have full control over, the relevant build options. Therefore, IMO Sphinx-based projects should at least explicitly state their standard sphinx invocation in their docs/contributing guide, to avoid having to parse it out of the highly complex Makefile (which was quite non-trivial) or leave users guessing—I don't see the harm in that.
I have even heard some talk of Sphinx getting rid of Makefile generation by default for these reasons, though I'm not sure what the current status of that is—as a Sphinx maintainer, maybe @AA-Turner can comment on that further.
There's a goal to move to a single sphinx command, which would obsolete make.bat and Makefile files. Personally I recommend the -m sphinx -M html . _build invocation, as it automatically creates appropriate subfolders per builder -- this would likely become the default under the new sphinx command.
A
Seems like this should be closed for a while now as it continues to work just fine, so I'm just going to go ahead and do it. If there are more problems, we can always re-open or open a new issue about it.