jterrace/sphinxtr

The Sphinx Thesis Resource

Introduction

Creating a PhD thesis is typically done using LaTeX. This works really well for producing a PDF, but a giant PDF file is not a great way to put documents on the web. There are solutions that exist to turn latex source files into HTML, but in my experience, they tend to produce poor HTML output.

The Sphinx project is a wonderful tool for creating portable documents, allowing for output to many different formats. Unfortunately, it has many shortcomings when trying to typeset something so advanced as a PhD thesis. The aim of this project is to modify Sphinx to support all of the needs of a thesis writer. Many of the patches are not appropriate for contributing directly to the upstream Sphinx repository, so this is instead a separate project.

This sphinxtr output is available in several formats at: http://jterrace.github.com/sphinxtr.

The source code for sphinxtr can be found at: https://github.com/jterrace/sphinxtr.

Installation

If you are running the apt packet manager you can install the requirements with the following command:

sudo apt-get install python-setuptools python-virtualenv texlive-full

Otherwise you can maybe find other ways to install the following packages:

• Python 2 (preinstalled on most systems)
• Setuptools (look for the most up to date version)
• Virtualenv
• Tex Live

Now create a virtualenv. This will help you to separate the requirements from this project from other Python projects you might have:

virtualenv venv
source ./venv/bin/activate

Note

You can get out of the virtualenv by either closing the terminal or by calling deactivate.

Then install the required Python packages:

pip install -r requirements.txt

Building

You need make. The following targets are supported:

html

Builds HTML format, separated into sections

singlehtml

Builds HTML format on a single page

text

Builds text files, separated into sections

singletext

Builds a single text file

latexpdf

Builds into latex source files and then compiles into a PDF. Requires latex.

Changes

The following changes and additions have been made from vanilla Sphinx:

• A cross-format bibtex bibliography based on sphinx-natbib
• Tables that can go inside figures
• Changed table formatting to look pretty, like booktabs
• Improved alignment in table environment
• Added support for short captions that show up in the "list of figures" section
• Changed equation reference formatting from "(1)" to "1"
• Full customization of latex preamble and style file
• Numbered figures
• Numbered section references
• A singletext output that builds into a single text file, similar to singlehtml
• A subfigure environment

Documents Using sphinxtr

• Jeff Terrace's PhD Thesis

sphinxtr's Issues

WAI-ARIA Roles

https://en.wikipedia.org/wiki/WAI-ARIA

http://www.w3.org/TR/wai-aria/roles

( https://bitbucket.org/birkenfeld/sphinx/pull-request/204/added-wai-aria-roles-to-themes-document/diff )

Add inline math example

Forgot to show how to use inline math.

Whitespace violations in code

I am working with some of the extensions, and was looking to modify/extend to my purpose.
The codebase contains many flake8 "triggers" - such as trailing whitespace, inconsistent indentation, unused imports.

Would you be open to a PR that fixes these events? I think I could also find a way to add it to the travis build cycle, so that the style will continue to be checked going forward.

Error using latexpdf

Hi,

I'd like to use sphinx to write my thesis, so I tried installing all requirements for sphinxtr and run make for both html and latexpdf targets (on the source tree downloaded from github).

The html target works fine, but not latexpdf, as this error pops up:
AttributeError: DocTranslator instance has no attribute 'verbatim'

it occurs on line 41 of latex_mods.py, in visit_Text.

I'm using MacOS X, with https://tug.org/mactex/.

Thanks

HTML output requires two builds for bibliography

Because of the way the :cite:refs directive works, the html and singlehtml output don't work on the first build. They have to be built a second time to get all of the references to be built correctly. I'm not sure how to have a directive stay unresolved until after all other documents have been built.

latex_mods.py extension breaks with Sphinx 1.5

Sphinx 1.5 refactored writers/latex.py significantly, breaking extensions\latex_mods.py at line 17:

  sphinx.writers.latex.HEADER = sphinx.writers.latex.HEADER.replace('\usepackage{sphinx}', '')

as HEADER is no longer used. It looks like solution is to replace the default latex template with one in _templates\latex.tex_t.

Installation not very clear

Hello!

In attempting to start using your libraries, there are no formal packages, making it not possible to either pip install sphinxtr from PyPI, nor using the direct source from GitHub, as there is no setup.py package either.
These would be helpful to get the package installed and usable quickly.

Here's a reference on Python packaging: http://python-packaging-user-guide.readthedocs.io/en/latest/distributing/

What is the license of the code?

I would like to use only a piece of an extension (numsec)
w/o pulling the whole code.
I presume 'CC-BY' is for the generated material or rst files, is it?

Responsive Web Design (Mobile/Tablet Support)

https://en.wikipedia.org/wiki/Responsive_web_design

• https://github.com/ryan-roemer/sphinx-bootstrap-theme
• https://github.com/tell-k/sphinxjp.themes.basicstrap

newlines doens't work in figtable multiline cells

Hi,
In normal RST simple tables, you can have several lines in a cell, usign plain line breaks. In https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#simple-tables this example is provided:

=====  =====
col 1  col 2
=====  =====
1      Second column of row 1.
2      Second column of row 2.
       Second line of paragraph.
3      - Second column of row 3.

       - Second item in bullet
         list (row 3, column 2).
\      Row 4; column 1 will be empty.
=====  =====

But this doesn't seem to work with figtables. It only works if ´|br|` is used instead of newlines?

latex_mods.py errors out on pictures without alt tag?

Not sure, if this is a bug or if I did something else wrong. I often got an error like this:

Exception occurred:
  File "/home/erikb85/coding/thesis/extensions/latex_mods.py", line 30, in visit_caption
    short_caption = look_node.get('alt', '').translate(tex_escape_map)
TypeError: expected a character buffer object

Research lets me guess, that you wrote that latex_mods.py yourself? Can't find it anywhere else on the net.

Anyways, with some debugging outputs I found that the look_node.get('alt','') returned an empty string. So I guessed that I needed an alt tag in my figures. I added one and suddenly I didn't get the error message any more.

If my guess is correct, then we should probably change the code, right? Having no alt tag shouldn't err out off the complete build. At least we should add a more meaningful error message than "TypeError".

Multi-paragraph caption of figtable (extend/document)

The changelog at http://jterrace.github.io/sphinxtr/singlehtml/index.html#changes mentions that short caption is now supported. LaTeX needs this for multi-paragraph captions. I wonder if this is the reason it was implemented, and how to input a multi-paragraph caption (multiple :caption:) with figtable? If not possible, could figtable be easily extended to handle that?

(and BTW, thanks for a great extension, you fixed the most shortcomings of sphinx for me. They should definitely upstream most of your work.)

How to add a Glossary?

Hi Jeff,

I'd like to add a glossary in the way you would do it. Here's what I did so far:

As in most of my sphinx projects I have a glossary.rst file. But the only way to add it, is via the toc.txt file. The problem is that by this way it becomes a chapter, but it should belong to the preamble sections like acknowledgements.

I got sphinxtr to already build a glossary.inc, but it doesn't get included in the final document. Trying to overwrite all appearances of dedication (which I don't need anyway in a Master thesis) with s/dedication/glossary/g in the ._tex files resulted in it not being able to build a pdf. Not sure how to continue with that goal. Any hints?

Name collision with backports package

There is a naming collision with the backports package, which is used to bring features from newer Python releases to Python 2.
If such a package is installed (for example backports.ssl_match_hostname which is needed by websocket and in turn by docker-py), it results in the following error:

Extension error:
Could not import extension numfig (exception: cannot import name OrderedDict)

Possible workarounds are using a virtualenv without system site packages, or renaming the extensions/backports.py module (used in extensions/numfig.py:5) to something else.

code syntax highlighting does not work in LaTeX

Hi,

Thank you very much for the well thought out and very useful code.

I have python code examples within my document. The html renders the syntax highlighting perfectly, but when I build latex (and from that pdf), the code comes up all jumbled up.

As a simple example, the following rest code...

..  code-block:: python

    >>> python main.py

comes out like this in the pdf:

\PYG {g+gp }{\PYGZgt{} \ PYGZgt{} \ PYGZgt{} } \PYG{n}{python} \PYG{n}{main}\PYG{o}{.}\
PYG{n}{py}

Can you please advise if I am doing something wrong, or which files I should be looking into to fix this?

Thanks,
MR

inconsistent formula numbering

Din't try to run your code, just compared PDF and HTML outputs. Formula (4.1) in PDF is numbered as (1) in HTML. This is inconsistent and wrong in HTML.

\PYGs not rendered

I have one more problem left until my current set of rest files will be compiled completely. Maybe you know something. I have a code snippet in python. Very small. It can be rendered in LaTeX with the normal Sphinx builder. It can also be rendered with both HTML renderers, from Sphinx as well as from Sphinxtr. But it can not be rendered in the LaTeX builder of Sphinxtr. There it looks like this:

I am currently not aware of any error messages and google also didn't find anything useful. Before I start digging into the code I thought you might know something.

numsec: Keep node structure

Is this still maintained?

I realized that numsec is relying on a particular structure of the reference nodes: it assumes there is an emphasis node (or some other kind of node) inside, and it removes it. I don't think it should alter the structure. If one wants to remove the emphasis node, it should be done somewhere else, not in this extension.

So I propose this code for the inner loop in doctree_resolved, to replace only the text nodes:

        if refdocname in secnums:
            secnum = secnums[refdocname]
            for child in node.traverse():
                if isinstance(child, nodes.Text):
                    text = child.astext()
                    toclist = app.builder.env.tocs[refdocname]
                    anchorname = None
                    for refnode in toclist.traverse(nodes.reference):
                        if refnode.astext() == text:
                            anchorname = refnode['anchorname']
                    if anchorname is None:
                        continue
                    linktext = '.'.join(map(str, secnum[anchorname]))
                    child.parent.replace(child, nodes.Text(linktext))

wrong captions for floating tables

Din't try to run your code, just compared PDF and HTML outputs. Tables are labled as "Figure x.x" and have the shared numbering with Figures. This is wrong, they should be labled as "Tables". Also, didn't check your LaTeX output, but keep in mind that cases where you have to specify exact float placement in LaTeX happen more often then one could expect.

LaTeX: natbib doesn't recognize "authoryear" option

For some reason my HTML generates citations with "authoryear" but my PDF doesn't. I'd really prefer to use this variation because I feel it is more commonly used in Germany. Adding some debugging prints to the natbib/__init__.py doesn't yield any output at all (only when processing the HTML generation). Any ideas what could be done here?

Issue when using numfig extension: can't compile HTML

(Issue brought over from sphinx-doc/sphinx#1864)

I'm using the numfig extension from the https://github.com/jterrace/sphinxtr package to generate proper numbering when referencing figures.

I reference figures using the code:

See Fig. :num:`fig-2dhisto`.

.. _fig-2dhisto:

.. figure:: _static/2d-histo.png
   :scale: 80 %
   :align: center

   Approximate center coordinate values....

In my system the HTML compiles, but the numbers are off as seen in the image below:

When I push the code to my repo (https://github.com/asteca/asteca-docs) the PDF compiles properly with the images perfectly numbered (see https://media.readthedocs.org/pdf/asteca/latest/asteca.pdf) .

The HTML on the other hand fails with the following output (accesible here: https://readthedocs.org/builds/asteca/2620960/):

html
-----


Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/sphinx/cmdline.py", line 254, in main
    app.build(force_all, filenames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/sphinx/application.py", line 212, in build
    self.builder.build_update()
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 214, in build_update
    'out of date' % len(to_build))
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 276, in build
    self.write(docnames, list(updated_docnames), method)
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 320, in write
    self._write_serial(sorted(docnames), warnings)
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 333, in _write_serial
    self.write_doc(docname, doctree)
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/sphinx/builders/html.py", line 433, in write_doc
    self.docwriter.write(doctree, destination)
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/sphinx/writers/html.py", line 51, in translate
    self.document.walkabout(visitor)
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/docutils/nodes.py", line 166, in walkabout
    visitor.dispatch_visit(self)
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/docutils/nodes.py", line 1882, in dispatch_visit
    return method(node)
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/sphinx/writers/html.py", line 588, in unknown_visit
    raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
NotImplementedError: Unknown node: num_ref

Exception occurred:
  File "/home/docs/checkouts/readthedocs.org/user_builds/asteca/envs/latest/local/lib/python2.7/site-packages/sphinx/writers/html.py", line 588, in unknown_visit
    raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
NotImplementedError: Unknown node: num_ref
The full traceback has been saved in /tmp/sphinx-err-w7S3WI.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!

big tables - whats the deal ?

Hi,

First off all thx for sphinxtr its really useful - I have come across a challenge when using big tables. then its hard to tame them. perhaps because my latex skills are low and / or I don't fully understand the :spec: within the figtable directive.

I have tried with to version a one thats goes many columns horizontal and another one doing it vertical (because I read that long tables over multiple pages seems to be supported https://github.com/jterrace/sphinxtr/blob/master/tex/preamble._tex)

i have done it in a branch "Big tables":

https://github.com/pellekrogholt/sphinxtr/blob/big_tables/ch-figs/index.rst

thx

//

pelle

 in 'Text' version

http://jterrace.github.io/sphinxtr/sphinxtr.txt

This subsection is Section 5.1.

http://pythonhosted.org/sphinxcontrib-restbuilder/ may be helpful?

Sphinx >= 1.3.0 breaks latex_mods (previous_spanning_row removed from the LaTeX builder)

mod_latex is not able to monkey-patch the latex writer starting with sphinx 1.3.0:

Exception occurred:
  File "/home/eudoxos/roro/vale-oman/roro2014/rep1/source/extensions/latex_mods.py", line 106, in depart_row
    if self.previous_spanning_row == 1:
AttributeError: DocTranslator instance has no attribute 'previous_spanning_row'

Searching the history revealed this changed in sphinx-doc/sphinx@5d96523.

Can not import numfig and natbib

I am running sphinx v1.2.3 and after downloading the github repo of this project, I went ahead and did make html. However, this import error was shown due to numfig:

Running Sphinx v1.2.3
Extension error:
Could not import extension numfig (exception: cannot import name OrderedDict)
make: *** [html] Error 1

I commented out the numfig extension, but then this error was shown due to natbib:

Running Sphinx v1.2.3
Extension error:
Could not import extension natbib (exception: cannot import name Set)
make: *** [html] Error 1

readme.md incorrectly links to PDF

Readme.md references http://jeffterrace.com/thesis/ as the URL for your thesis PDF. It should be http://jterrace.github.io/sphinxtr/sphinxtr.pdf

figtable from csv

Would be great to have posibility to load table data from csv.
Maybe :file: and :widths: param to figtable directive like in csv-table directive?

.. csv-table::
:widths: 50, 50
:file: table.csv

numfig bug: :page: references wrong label from one chapter to another

Hi Jeff,

found a bug in numfig.py which can be seen, when :page: reference is one in chapter A but the figure referenced is in chapter B. The current numfig will generate the incorrect latex. Example:

figure \ref{ch-impl/index:fig-desk} on page \pageref{ch-eval/index:fig-desk}

(the \ref block is correct, but the \pageref is wrong, because that label doesn't exist)

I fixed it by copying a lot of code from latex_visit_num_ref to latex_visit_page_ref locally and the page ref method looks like this now:

def latex_visit_page_ref(self, node):
    fields = node['reftarget'].split('#')

    if len(fields) > 1:
        label, target = fields
    else:
        label = None
        target = fields[0]

    if target not in self.builder.env.docnames_by_figname:
        raise nodes.SkipNode
    targetdoc = self.builder.env.docnames_by_figname[target]

    ref_link = '%s:%s' % (targetdoc, target)
    self.body.append("\\pageref{%s}" % ref_link)
    raise nodes.SkipNode

The code is neither optimal nor did I bother to make a commit out of it for now. I mostly want to keep the note here to make this a pull request after I am done with my thesis. Maybe this can be changed already when we replace some of the copy&paste files with a requirements.txt file and get the public numfig project. What do you think? (take your time responding, I know you are busy)

ccicons on ubuntu

Not sure how to install required ccicons package on ubuntu

ePub / Mobi (ebook formats)

Support for ebook formats (like ePub and mobi) might be helpful, as well.

• ePub: http://sphinx-doc.org/latest/builders.html#sphinx.builders.epub.EpubBuilder
• mobi: https://bitbucket.org/birkenfeld/sphinx/issue/739/please-add-a-mobi-builder

re: KindleGen

The Linux version of kindlegen doesn't recognize the -rebuild option

Tables are in List of Figures not List of Tables

Hi Jeff,

I have a new minor issue. I created a table with the figtable directive. The code looks as follow, the table is generated exactly as desired and a figure for it is generated, but is recognized as figure not as table.

.. figtable::
    :label: table-states-conn
    :caption: Transtion Table of Connection State Machine

    +-------+-----------------+--------------------------------------+
    | State |      Event      |                         Action       |
    +=======+=================+======================================+
    |       |                 |                                      |
    | Shell | cmd_received    | transition to Find                   |
    |       |                 |                                      |
    +-------+-----------------+--------------------------------------+
    |       |                 |                                      |
    | Find  | prompt_received | execute command; transition to Shell |
    |       |                 |                                      |
    +-------+-----------------+--------------------------------------+
    |       |                 |                                      |
    | Find  | auth_needed     | execute authentication method;       |
    |       |                 | transition to Auth                   |
    |       |                 |                                      |
    +-------+-----------------+--------------------------------------+
    |       |                 |                                      |
    | Auth  | prompt_received | execute command; transition to Shell |
    |       |                 |                                      |
    +-------+-----------------+--------------------------------------+

Is that expected? I also see the same in the examples here and your thesis. If this is expected behaviour you can close this issue.

colorlinks instead of bordered links for PDF

From the default Sphinx I am used the very beautiful colored links (personal opinion), that can be set with

\usepackage[colorlinks]{hyperref}

What would be the way to insert that option into sphinxtr? Would you also like it as default, maybe with some tuning to the colorspace? What would be necessary to get this as an option to the conf.py?