开发者

How to create a PDF in reStructuredText?

开发者 https://www.devze.com 2023-02-01 13:38 出处:网络
The documentation for the uncertainties Python package is written in reStructuredText, for the Sphinx documentation system.The HTML looks fine.I would like to create a PDF version.The goal is to have

The documentation for the uncertainties Python package is written in reStructuredText, for the Sphinx documentation system. The HTML looks fine. I would like to create a PDF version. The goal is to have a "chapter" for each of the web page.

However, what happens is that the PDF generated by the ReST files transforms the (HTML) sections of index.html into individual chapters (which I don't want: the PDF should have them as sections too). Another problem is that all HTML pages after the main page appear in the PDF as subsections of the section where the toctree directive appears (i.e., in the Acknowledgment section of the main page).

So, how should the ReST file be structured so that (1) the web documents look the same as they are now, and (2) each web page corresponds to a PDF chapter. Any help would be much ap开发者_运维知识库preciated!


There is a solution. If I remember correctly, the key points were:

  • Use a special Table of Contents as the master document (I used index_TOC.rst instead of the default index.rst): in conf.py
    • master_doc = 'index_TOC'
    • latex_documents = [('index_TOC', 'uncertaintiesPythonpackage.tex',…]
  • The new Table of Contents file index_TOC.rst contains a ToC like

    TOC
    ===
    
    .. toctree::
       :hidden:
       :maxdepth: 1
    
       index
       user_guide
       numpy_guide
       tech_guide
    

Thus, the web version still opens onto the main index.rst text, and the PDF (LaTeX) version has each ReST file in a separate chapter.

0

精彩评论

暂无评论...
验证码 换一张
取 消