sfstoolbox/sfs-python

DOC: handling of PDF and EPUB version

hagenw opened this issue · 4 comments

hagenw commented

The official documentation on readthedocs is build as HTML, PDF, and EPUB. In CONTRIBUTING.rst we describe only how to build the HTML version.

We should improve this situation by one of the following solutions:
1.) Add documentation on howto build PDF and EPUB documentation locally as a contributor is supposed to check that the documentation builds fine if she/he makes changes.
2.) Remove the PDF and EPUB versions from readthedocs and focus on HTML.

mgeier commented

I prefer option 1.

fs446 commented

I'd prefer at least PDF support additionally to HTML, thus voting for option 1.

hagenw commented

OK, I'm also in favor of 1.).

Should we then add the following to the documentation:

# EPUB
python setup.py build_sphinx -b epub
# PDF
python setup.py build_sphinx -b latex
cd build/sphinx/latex
make

Or is there a better way to generate the PDF locally?

mgeier commented

Using make is not very platform-independent.

I normally use:

cd build/sphinx/latex
latexmk -pdf

... but on Windows, you might have to install Perl for this to work.

I would leave the creation of the PDF to the user and just recommend latexmk, see https://nbsphinx.readthedocs.io/en/0.4.2/usage.html#Running-Sphinx.