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
2
votes
0 answers

WARNING of duplicate C++ declaration/object description (for namespace) when use "doxygenfile" objective for different source files

I want to use doxygen and sphinx to generate documents for source file, in the rst file, I use "doxygenfile" to introduce the source file, like .. doxygenfile:: Headerfile1.hpp :project: MyProject .. doxygenfile:: Headerfile2.hpp :project:…
xiaojuan
  • 21
  • 1
2
votes
1 answer

Sphinx - ran`make html` and I am missing content for a few modules

Repo link: https://github.com/Eric-Cortez/aepsych-fork Problem: I am running into an issue when generating sphinx documentation when I run make html most of the modules are generated except for 3 which are aepsych.database, aepsych.plotting, and…
Eric Cortez
  • 31
  • 4
2
votes
2 answers

Cloudflare Pages uses different sphinx version depending on commits and one is failing

I have a Cloudflare page that uses python-sphinxto build docs. For some of my commits, it downloads a different version of sphinx than others and fails to build docs correctly. What I tried: Adding a dummy commit on top of a failing build seems to…
Bartek Lachowicz
  • 139
  • 8
2
votes
0 answers

Sphinx recursive autosummary not importing modules

I'm going crazy with Sphinx's recursive autosummary. My working directory is: my_wd | |-- docs | |-- source | |--index.md | |--conf.py | |-- _templates | |-- custom-module-template.rst | |--…
sato
  • 768
  • 1
  • 9
  • 30
2
votes
0 answers

Nested nodes in sphinx extension

I am trying to make a sphinx extension (for html output) that generates a code block and inserts text and spans into it. However when I create a literal_block (code block) and add inlines (spans) to it, only the text of the inline nodes will appear…
Jonas
  • 56
  • 6
2
votes
1 answer

How to remove "Built with Sphinx using a theme provided by Read the Docs." from RTD theme built docs?

How can I remove the sentence that's shown underneath each page that's built using RTD theme: "Built with Sphinx using a theme provided by Read the Docs." It's my understanding that the RTD theme is released under MIT license. My project has one…
bad_coder
  • 11,289
  • 20
  • 44
  • 72
2
votes
0 answers

How to autodoc a custom descriptor like a property in sphinx?

I have a custom descriptor @runtime_checkable class ROProperty(Protocol[T_co]): """Protocol for a read-only descriptor.""" def __get__(self, instance: Any, owner: Any = None) -> T_co | None: ... class…
demberto
  • 489
  • 5
  • 15
2
votes
1 answer

PandocMissing when building Sphinx documentation

I am working on using GitHub Actions to build and deploy some Sphinx documentation to GitHub pages and am running into a problem. When the action runs, I get the error: Notebook error: 183 PandocMissing in examples/Admissions Data.ipynb: 184 Pandoc…
Ethan
  • 876
  • 8
  • 18
  • 34
2
votes
1 answer

How to remove repeating "toc" from the bottom of the index page in sphinx?

Here's my index.rst: Welcome to the documentation! ============================= .. include:: readme.rst .. _INTRODUCTION:: .. toctree:: :maxdepth: 1 :caption: Introduction readme .. toctree:: :maxdepth: 1 :caption: Contents: …
paul-shuvo
  • 1,874
  • 4
  • 33
  • 37
2
votes
1 answer

Include a custom directive into another custom directive

Following Sphinx TODO directive tutorial, I have made a Sphinx custom directive (let's call it A) that takes a file path as input, extracts information from this file, and produce nodes accordingly. I want to create a new custom directive (let's…
Silverspur
  • 891
  • 1
  • 12
  • 33
2
votes
3 answers

Type aliases in type hints are not preserved

My code (reduced to just a few lines for this demo) looks like this: AgentAssignment = List[int] def assignment2str(assignment: AgentAssignment): pass The produced html documentation has List[int] as the type hint. This seems to be a…
AlwaysLearning
  • 7,257
  • 4
  • 33
  • 68
2
votes
1 answer

Sphinx docxbuilder and custom extension

I have a custom node defined in an extension (in a similar way as TODO example on sphinx page). Problem is that this extension is used for html output via visit_my_node/depart_my_node methods, but I would have liked to implement a similar thing for…
ThylowZ
  • 55
  • 7
2
votes
1 answer

Docstrings for overloaded functions with .. autofunction:: in Sphinx

I have an issue with using the Sphinx's .. autofunction:: directive on a function that has multiple @overload decorators. While prototypes of the functions are included, the docstrings I want are not. What it generates: What I want is something…
David Hožič
  • 235
  • 2
  • 7
2
votes
1 answer

Sphinx hiding modules imported in __init__.py

My package has a structure, similar to the following: ├── README.md ├── __init__.py ├── module1 │ └── submodule1.py │ └── submodule2.py ├── module2 │ ├── __init__.py │ ├── _hiden_submodule1.py │ ├── _hiden_submodule2.py │ └──…
Liris
  • 1,399
  • 3
  • 11
  • 29
2
votes
1 answer

MyST-Parser: Auto linking / linkifying references to bug tracker issues

I use sphinx w/ MyST-Parser for markdown, and I want GitHub or GitLab-style auto linking (linkfying) for references. Is there a way to have MyST render the reference: #346 In docutils-speak, this is a Text node (example) And behave as if it…
tony
  • 870
  • 7
  • 16
1 2 3
…
99 100