Stack Overflow
Stack Overflow

Questions tagged [python-sphinx]

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation. Sphinx is especially suitable for Python documentation, but it is a general-purpose tool that can be used to document anything.

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.

It was originally created for the new Python documentation, and it has excellent facilities for the documentation of Python projects, but C/C++ is already supported as well, and it is planned to add special support for other languages as well.

Sphinx is under constant development. The following features are present, work fine and can be seen “in action” in the Python documentation:

  • Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text.

  • Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information.

  • Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children.

  • Automatic indices: general index as well as a module index.

  • Code handling: automatic highlighting using the Pygments highlighter.

  • Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more.

Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.

See also:

3663 questions
29
votes
3 answers

Sphinx and argparse - autodocumenting command line scripts?

I'm building a Python package, and using Sphinx to create the docs. Aside from my package code, I also include a lot of command line Python scripts, which use argparse. I was wondering if there is a way to get Sphinx to autodocument these scripts?…
jeremiahbuddha
  • 9,701
  • 5
  • 28
  • 34
28
votes
2 answers

How do I create a global role/roles in Sphinx?

This is a followup of "ReST Strikethrough" ReST strikethrough but in a Sphinx rather than ReST context. My question is whether there is a central place in sphinx where to put a "role" directive or whether this directive really has to be repeated in…
Bud P. Bruegger
  • 1,021
  • 10
  • 15
28
votes
8 answers

How to generate Microsoft Word documents using Sphinx

Sphinx supports a few output formats: Multiple HTML files (with html or dirhtml) Latex which is useful for creating .pdf or .ps text How can I obtain output in a Microsoft Word file instead? With another doc generator I managed to generate a…
Andrea Francia
  • 9,737
  • 16
  • 56
  • 70
28
votes
2 answers

How do I break a link in a rst docstring to satisfy pep8?

I'm using Sphinxdoc to generate api documentation, and I've run into a problem with pep8 conformance when writing a docstring. As you can see below, the link to the OWASP site ends at column 105, far past what pep8 dictates maximum-line-length def…
thebjorn
  • 26,297
  • 11
  • 96
  • 138
27
votes
3 answers

How can I configure Sphinx to conditionally exclude some pages?

When generating documentation using Sphinx, I would like to be able to generate two versions of my documentation: one including everything, and one with only a particular set of pages. What's the best way of achieving that? I could write a build…
kdt
  • 27,905
  • 33
  • 92
  • 139
27
votes
1 answer

docstring in class or __init__ constructor?

There seem to be two places where you can put docstrings for a class: Right under the class definition: class MyClass: """Summary of MyClass. Body. """ Right under the __init__ constructor: class MyClass: def __init__(self, arg1,…
Jin
  • 778
  • 1
  • 8
  • 23
27
votes
2 answers

Is there a Sphinx reST Python docstring field for yields?

I'm trying to use reST-style docstrings, i.e. def foo(bar): """a method that takes a bar :param bar: a Bar instance :type bar: Bar Is there a standard way to document yields? I looked at…
gatoatigrado
  • 16,580
  • 18
  • 81
  • 143
27
votes
5 answers

Generating PHP code documentation with Sphinx?

Sphinx is a Python library to generate nice documentation from a set of ReST formatted text files. Not the tool used for full-text searching I'm also fully aware of doxygen / phpdoc tools. I'm trying to figure out if there is a way of using Sphinx…
messedup
  • 1,098
  • 1
  • 10
  • 12
27
votes
1 answer

Marking classes and/or methods as deprecated in Sphinx

Is there any way to mark a class and/or method as deprecated in Sphinx? I can only find a deprecated option for modules. Using a generic admonition would work, but wouldn't carry the semantic meaning.
Ernst
  • 562
  • 4
  • 8
26
votes
2 answers

Combining Sphinx documentation from multiple subprojects: Handling indices, syncing configuration, etc

We have a multi-module project documented with the (excellent) Sphinx. Our setup is not unlike one described on the mailing list. Overall this works great! But we have a few questions about doing so: The submodule tables of contents will include…
Ken Arnold
  • 1,942
  • 1
  • 20
  • 24
26
votes
1 answer

Unknown directive type "toctree". Error in Pycharm, but index.html works

When working in PyCharm, the preview mode of the document I am creating in Sphinx shows: System Message: ERROR/3 (, line 9) Unknown directive type "toctree". ..toctree:: :maxdepth: 2 file1 file2 I have included the autodoc extension in…
Wouter
  • 477
  • 2
  • 6
  • 8
26
votes
2 answers

How to specify different return types in python docstring

I'm currently writing documentation for my python package using Sphinx and the autodoc plugin. For a function return value I can e.g. write :returns: int: count which tells sphinx that there is a return value of type int, named count. I now got a…
Igl3
  • 4,900
  • 5
  • 35
  • 69
26
votes
4 answers

Change the colors of the Sphinx Read The Docs theme?

I'm building documentation for my API library and I'm having readthedocs.io host the documentation, and is backed with Sphinx. I have the Read The Docs theme installed for Sphinx using pip install, and the Read the Docs website currently has the…
falling cat
  • 363
  • 1
  • 4
  • 8
26
votes
3 answers

Python Sphinx exclude patterns

I'm generating documentation with Sphinx for project with structure like this : + project | +- docs | +- tests | +- workflow -+- definitions -+- | +- I want to exclude tests, and…
jmt
  • 719
  • 1
  • 9
  • 28
26
votes
1 answer

Is doctrees folder required for displaying html docs with Sphinx?

When hosting docs built with Sphinx, the build folder has two subdirectories: doctrees and html. Do I need both folders to display the docs correctly or only the contents of the html folder? If I do need both, do the contents of the html folder go…
Dan
  • 4,488
  • 5
  • 48
  • 75
1 2 3
…
99 100