Professional Book like structure with Sphinx

Initially, Sphinx was designed to generate Python documentation. But, it can also be used for many things. I am currently using it to write my own book @eclipsebook.in. The advantage for me is that I can write my book in reStructuredText and can generate different formats with ease.

Here is an insight how I am tweaking/using sphinx.

Separate Master Doc

Appendix is handled differently in HTML & PDF. For HTML edition, it is just another chapter/part. For PDF, it is a separate directive. More importantly, the Appendix entries get promoted to extra one level. For that I have toc.rst for HTML and latex-contents.rst as the Master Doc

Also, there is a separate Appendix file for HTML and PDF. HTML gets default :toctree: for Appendix, latex get’s it with a little tweak.

Here is appendix file for Latex:

%%%%%%%%%%
 Appendix
%%%%%%%%%%

.. include:: acronyms.rst
.. include:: credits.rst
.. include:: testimonials.rst
.. include:: trademark-attribution.rst
.. include:: ../contact.rst
Custom Prolog and Epilog

This is what the conf.py contains:

rst_prolog = "n.. include:: /%s/include-pre.txtnn"%(os.path.abspath('..'),)

rst_epilog = "n.. include:: /%s/include-post.txtnn.. include:: /%s/include-post-conf.txtnn"%(os.path.abspath('..'),os.path.abspath('.'))

Interestingly, there are two epilogs, one configuration directory specific, and other configuration specific. Why separate? Figure out yourself.

this is HTML post include:

.. |IDE|                replace:: :abbr:`IDE (Integrated Development Environment)`
.. |JVM|                replace:: :abbr:`JVM (Java Virtual Machine)`

this is latex post include:

.. |IDE|                replace:: :abbr:`IDE`
.. |JVM|                replace:: :abbr:`JVM`

The tag :abbr: is good for HTML. The expansion is shown on Hover. But, in PDF it seems to gets expanded at every instance.

PDF Tweaks

In Sphinx PDF, everything gets a chapter number. That does not seem to be convention, at least with normal printed Books. To make sure that the generated pdf is more-or-less like printed book, I have done following tweaks

The first page of my book is copyrights.rst. (See http://eclipsebook.in/toc/ ) to know the order of pages.

This is how my copyrights.rst looks like

.. raw:: latex

   %%% MEERA-TODO-PDF-PATCH
   %%% From above comment out tableofcontents

   setcounter{secnumdepth}{-1}

   %%% MEERA-TODO-PDF-PATCH
   %%% From below comment out part{Copyrights}

Copyrights
==========

|copy| MMIX-MMX Meera P. Ghumalia.  All rights reserved.

<Some More Contents>
<Some More Contents>
<Some More Contents>

.. raw:: latex

   tableofcontents

   renewcommand{chaptermark}[1]%
   {}{}
   renewcommand{sectionmark}[1]%
   {}{}
   renewcommand{headrulewidth}{0.5pt}
   renewcommand{footrulewidth}{0pt}
   fancyhf{}
   fancyfoot[C]{thepage}
   fancyhead[RO]{}
   fancyhead[LE]{}

   %%% MEERA-TODO-PDF-PATCH
   %%% From below comment out part{preface}
   %%% and chapter{Dedication}

Diff / Patch Script

I create a “patch (diff)” file, and for every build, PATCH the generated tex file with a modifiled makefile:

latex: $(PREREQUISITES)
        $(SPHINXBUILD) -b latex $(LATEXSPHINXOPTS) $(BUILDDIR)/latex
        -@rm $(BUILDDIR)/latex/*.orig
        @echo ===== Patching Start =====
        patch -p0 $(BUILDDIR)/latex/c-cpp-eclipse.tex < book/conf/latex/c-cpp-eclipse.tex.diff
        @echo ===== Patching End =======
        @echo .
        @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
        @echo "Run `make all-pdf' or `make all-ps' in that directory to" 
              "run these through (pdf)latex."

Now, I create a Patch file. It’s quite simple. Idea is to create the virgin .tex file, and then follow the comments already embodied in the generated file. These are the steps:

make clean
sphinx-build -b latex -d build/latexdoctrees -c book/conf/latex -D latex_paper_size=a4  book build/latex
cp build/latex/c-cpp-eclipse.tex .

# Edit generated "LayTech" file and follow the Comments.
emacs build/latex/c-cpp-eclipse.tex

diff -U4 c-cpp-eclipse.tex build/latex/c-cpp-eclipse.tex > book/conf/latex/c-cpp-eclipse.tex.diff
rm c-cpp-eclipse.tex

Rarely, after upgrading Sphinx, my build starts breaking. So, I create the patch file again.

Drop in your comments if you find my steps complicated, or if you have some further question.

One thought on “Professional Book like structure with Sphinx”

Comments are closed.