I am using sphinx-build to create both html and latexpdf output. Output looks amazing in both cases.
I would like to pass the project name on the command-line so the documentation can be titled e.g., TEST. This works great for the html option. In the example below (from a modified make.bat file), TEST overrides any project definition in the conf.py file.
%SPHINXBUILD% -b html -D project ="TEST" %ALLSPHINXOPTS% %BUILDDIR%/html
However, the command–line option is ignored when the tex file is created and whatever was in the conf.py is used for the definition of project in the generated PDF file.
%SPHINXBUILD% -b latexpdf -D project ="TEST" %ALLSPHINXOPTS% %BUILDDIR%/html
For example, if project is defined in conf.py: project = 'TEST'
Then used in the preamble: \title{project}
The document is titled TEST. I cannot seem to override the TEST value with a command-line argument.
Thanks for the reference to latex_elements. I realize that what I was trying to do, override settings in conf.py on the fly by using command-line arguments, is not going to work.
Related
The path to the master doc of a Sphinx build can be specified in conf.py. However, this directory path is reflected in the generated HTML, and shows for example in Read The Docs as a missing index. I'd like to use this alternative path to structure my project cleanly - to have configuration at the top level and documentation inside src, but have the build essentially get rid of it.
So here's what I had previously:
docs
conf.py
index.rst
things
doc1.rst
doc2.rst
This works, but when lots of files are added to the top level, it gets messy with Sphinx's makefiles etc. I'd like to have this instead:
docs
conf.py
src
index.rst
things
doc1.rst
doc2.rst
Which builds, but index.html is in build/html/src instead of build/html. I was surprised to find no information on this, other than the fact that master_doc in conf.py controls the location and name of the main file. How could I get my documentation to be built to build/html?
There is an option for specifying the location of the configuration file: -c.
# conf.py
master_doc = 'index'
# structure
docs
conf.py
src
index.rst
...
Then run sphinx-build -b html -c . src build/html. However, this solution indeed needs control over the build command, which is not available in Read The Docs. And it seems that -c doesn't work in Sphinx's own makefiles either (with -M instead of -b).
I have an existing project with the following directory structure:
docs/
conf.py
Makefile
index.rst
documentation-foo.rst
documentation-bar.rst
src/
...code...
common.mk
Makefile
README.rst
In the root of the repository, the Makefile contains various useful commands related to making, testing, packaging, and deploying the code. Likewise, common.mk includes a check to make sure the user has several utility programs available on their system (e.g., jq for manipulating/displaying JSON) that cannot be installed with pip. I can issue commands like make lint or make test and those are defined in that Makefile. (The top of the Makefile also has an include common.mk, see below for Makefile contents.)
In the docs/ folder, the Makefile is automatically generated by Sphinx. This Makefile is standalone and is totally independent of the Makefile or common.mk files in the root of the repository. I can issue commands like make html and it will use Sphinx to generate the documentation in HTML format.
Contents of (root) /Makefile:
include common.mk
clean:
...
lint:
...
test:
....
Contents of (root) /common.mk:
ifeq ($(shell which jq),)
$(error Please install jq using "apt-get install jq" or "brew install jq")
endif
Contents of (sphinx) /docs/Makefile:
# Minimal makefile for Sphinx documentation
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
...
My primary question is this: how can I incorporate the rules from the sphinx Makefile at /docs/Makefile so that they are available from the root level /Makefile?
For example, to make HTML documentation, I currently have to cd docs && make html from the root of the repo, but I would like to be able to run make html from the root of the repo and have the Makefile in the root of the repo resolve the target to the html target defined in docs/Makefile and use the rule defined in that Makefile.
Second, related question: if I have commands in docs/Makefile that have relative paths, must the paths be updated to be relative to the location where the make command is being run (the root of the repo instead of docs/), or does make resolve relative links to be relative to the Makefile's location in docs/?
You can do this with recursive make:
html:
$(MAKE) -C docs html
Some people strongly dislike recursive make. You can read the arguments against it, but I don't believe they apply to your use of make, since you're not trying to express dependencies.
I use sphynx to generate documentation from static .rst files (no docstrings extraction).
I have two files in my repository:
index.rst
.. toctree::
intro
and intro.rst
Will be skipped
===============
Where is my parent section?
---------------------------
Second section
==============
Below is screenshot of pdf obtained by running sphinx-build -b latex . _build; cd _build; pdflatex * :
Flabbergasting or what?
Thanks for providing the working example. I can reproduce your observation with Sphinx 1.2.3 on Windows. As far as I can see, the HTML output is working as expected. With the LaTeX builder, the following document structure is produced:
\chapter{Where is my parent section?}
\label{intro:will-be-skipped}\label{intro::doc}\label{intro:where-is-my-parent-section}
\chapter{Second section}
\label{intro:second-section}
I found suspicious about your document that it did not define a title. As a workaround I have found that adding a higher hierarchy works, whereas it does not matter if you put it into index.rst or intro.rest. This is the modified index.rst:
=====
TITLE
=====
.. toctree::
intro
Resulting in:
I have then further looked out for this problem, and found this Bitbucket/GitHub issue dealing with the very same issue (it is from 2011):
https://bitbucket.org/birkenfeld/sphinx/issue/632/section-versus-chapter-oddity-in-latex
https://github.com/sphinx-doc/sphinx/issues/632
Quote:
Your index.rst doesn't have a title, right? Basically Sphinx gobbles
up the most toplevel title (which is then replaced by the document
frontmatter).
That issue was put "on hold" back in 2011, probably it was not considered failing behavior. It was then just recently closed on GitHub without being "fixed". So, as Georg wrote in that ticket, Sphinx indeed just consumes the highest hierarchy whereas its content does not appear anywhere.
Therefore: adding a "title hierarchy", no matter how you name it, is the proper solution.
Using Ubuntu 14.04 and texlive if I create a new Sphinx project with sphinx-quickstart (separate source and build directories), drop the example files into the source directory and build with:
$ make latexpdf
I see the see the Will be skipped heading in the PDF output.
The OPs original command was
$ sphinx-build -b latex . _build; cd _build; pdflatex *
to build the documentation, which is slightly different than the latexpdf target in the Makefile which uses latex all-pdf. However, if I create a new project directory with the same conf.py that sphinx-quickstart created I still see the Will be skipped output in the PDF using the OPs command sequence. I would look into the conf.py settings that you are using, those might give a clue to the solution.
I understand that the following generates rst for all modules, excluding the index.rst
sphinx-apidoc -f -o very_good_docs/ very_good
And the following generates everything, including index.rst, conf.py, Makefile, etc
sphinx-apidoc -F -f -o very_good_docs/ very_good
The problem is that sphinx-apidoc does not generate a correct conf.py, so I have to always manually modify conf.py to include the correct sys.paths. If I modify my python code in "very_good" folder, I should run the sphinx-apidoc command without "-F", so conf.py is preserved. However, if I add a new module under very_good directly, index.rst is not updated without the "-F" option, which means my new module will not be in the doc. I guess the solution is to either someone generates the index.rst file only, or using "-F" option without overriding the conf.py. Is there a way to do it?
This is something I'm experiencing right now. It's really frustrating not finding information to achieve something so common.
My approach is to use a custom config.py and specifying it always I execute sphinx-build with the -F option. This way my config.py is not overwritten even if a new (and useless) config.py is created.
In order to specify a custom config.py you should use the -c option as stated in the documentation:
-c path
Don’t look for the conf.py in the source directory, but use the given configuration directory instead. Note that various other files and paths given by configuration values are expected to be relative to the configuration directory, so they will have to be present at this location too.
New in version 0.3.
The command will look like this:
sphinx-build -b html -c %sphinxConfigDir% %sourceCode% %buildDir%
I'm kind of a rookie with python unit testing, and particularly coverage.py. Is it desirable to have coverage reports include the coverage of your actual test files?
Here's a screenshot of my HTML report as an example.
You can see that the report includes tests/test_credit_card. At first I was trying to omit the tests/ directory from the reports, like so:
coverage html --omit=tests/ -d tests/coverage
I tried several variations of that command but I could not for the life of me get the tests/ excluded. After accepting defeat, I began to wonder if maybe the test files are supposed to be included in the report.
Can anyone shed some light on this?
coverage html --omit="*/test*" -d tests/coverage
Create .coveragerc file in your project root folder, and include the following:
[run]
omit = *tests*
Leaving this here in case if any Django developer needs a .coveragerc for their project.
[run]
source = .
omit = ./venv/*,*tests*,*apps.py,*manage.py,*__init__.py,*migrations*,*asgi*,*wsgi*,*admin.py,*urls.py
[report]
omit = ./venv/*,*tests*,*apps.py,*manage.py,*__init__.py,*migrations*,*asgi*,*wsgi*,*admin.py,*urls.py
Create a file named .coveragerc on your projects root directory, paste the above code and then just run the command:
coverage run manage.py test
In addition, if you want the tests to execute faster run this command instead.
coverage run manage.py test --keepdb --parallel
This will preserve the test DB and will run the tests in parallel.
You can specify the directories you want to exclude by creating a .coveragerc in the project root.
It supports wildcards (which you can use to exclude virtual environment) and comments (very useful for effective tracking).
The below code block shows how omit can be used (taken from the latest documentation) with multiple files and directories.
[run]
omit =
# omit anything in a .local directory anywhere
*/.local/*
# omit everything in /usr
/usr/*
# omit this single file
utils/tirefire.py
In your case, you could have the following in your .coveragerc:
[run]
omit =
# ignore all test cases in tests/
tests/*
For your question on coverage reports, you can think about testing and coverage in the following manner:
When you run pytest or unittest, all the test cases for your source code are executed
When you run coverage, it shows the part of the source code that isn't being used.
When you run pytest with coverage (something like pytest -v --cov), it runs all test cases and shows the part of the source code that isn't being used.
Extra:
You can also specify the location of your HTML report in the configuration file like:
[html]
directory = tests/coverage/html_report/
This is going to create html, js, css, etc. inside tests/coverage/html_report/ everytime you run coverage or pytest -v --cov
You can also explicitly specify which directory has the code you want coverage on instead of saying which things to omit. In a .coveragerc file, if the directory of interest is called demo, this looks like
[run]
source = demo