2

I'm currently working on a project (for university) that will be documented with LaTeX. About one third of the documentation will be about a python module that I've written.

I'm looking for a clean way to include the documentation generated by Sphinx into my main document. I think it would be possible to fiddle with the generated doc (remove preamble, move required \usepackage-commands in my main file, shift all headings down one level, etc.) and then include it, but I really hope that there is a better way.

I don't think that using Sphinx for the whole document would be a good idea since I'm not that confident in using it for more than code documentation.

Any hints are really appreciated!

  • Welcome to TeX.SX! You can use rst2latex.py to convert rst documentation into latex. It is sometimes a little rough but mostly OK. – Andrew Oct 7 '14 at 12:47
  • Thanks for the rst2latex-hint, but does this cover the documentation pulled from the python code? E.g. auto-generated method signatures. – Jasper Oct 7 '14 at 14:36
  • I've never done this, so I'm not sure...my impression though is that sphinx can be configured to do precisely this...I'm pretty sure that this is what sage does to produce its manuals. Sorry that I can't be of more help. – Andrew Oct 8 '14 at 4:47
3

It took me some time to figure this out, but as I just wanted to do the exact same thing, here you go 9 months later:

  1. Copy sphinx.sty to your main projects folder
  2. Add the following packages to your main file preamble:

    \usepackage{standalone}
    \usepackage{sphinx}
    
  3. Include your sphinx documentation like this:

    \part*{Appendix}
    \phantomsection
    \addcontentsline{toc}{part}{Appendix}
    \appendix
    \def\maketitle{}
    \def\tableofcontents{}
    \input{../project_name/doc/_build/latex/project_name}
    

This adds a nice, unnumbered part to the TOC and gives all the documentation sections letters as section numbering. It works for me with a completely untouched sphinx LaTeX output.

  • 1
    Why copy tabulary.sty? – Werner Jul 22 '15 at 17:24
  • Hmm, it is supplied with the sphinx output and required by sphinx.sty, so I figured that might be a good idea. But you could probably load it from CTAN just as well, I'll edit that out. – xfxian Jul 22 '15 at 18:35
  • Please note that this will fail with more recent Sphinx versions: there are more sphinx*.sty files in latex build repertory that you need to copy over if you want the latex code to be inserted into some other non-Sphinx generated document. – user4686 Jun 20 '17 at 22:22

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.