Questions tagged [docutils]

a general purpose document processing system written in Python.

Filter by
Sorted by
Tagged with
0 votes
0 answers
23 views

How to create new documents with a sphinx extension

From a sphinx extension, how do I create new documents (new page) under the current document that called my extension. I.e, I have an extension that is called from a rst file. Something like: foo.rst ...
Breno Leitão's user avatar
0 votes
1 answer
39 views

How to add a reference in a Sphinx custom directive?

I'm creating a custom directive to display the list of all the available components in pydata-sphinx theme. I try to avoid using the raw directive so I'm building a custom one to remain compatible ...
Pierrick Rambaud's user avatar
1 vote
0 answers
51 views

How to loop over all documents and get meta information about existing directives in Sphinx?

I would like to create a custom Sphinx extension, that shows a list of all figures. Also see related question How to create list of all figures (tables) in Sphinx? In the Sphinx documentation there is ...
Stefan's user avatar
  • 10.5k
0 votes
0 answers
43 views

Display a literalinclude block within a README.rst in GitHub

Goal. Display a literalinclude block within a README.rst in GitHub. Problem. I'm working on generating documentation for a Python project using Sphinx. The README.rst file has a literalinclude block (...
Elrond's user avatar
  • 2,012
0 votes
0 answers
78 views

Error using literalinclude with sphinx in .rst

I'm working on generating documentation for a Python project using Sphinx. I want to include code snippets from example files using the literalinclude directive. However, I keep getting the error &...
Elrond's user avatar
  • 2,012
0 votes
0 answers
100 views

Sphinx adds span with class colon to the header

We have a project which produces html from rst files, using Sphinx. Earlier we used Sphinx version 2.1 and after upgrade to version 6.1.3 a sideeffect occurs where our headers defined like this: :...
ms3300's user avatar
  • 216
0 votes
0 answers
50 views

How can I implement automatic multilevel list numbering in sphinx restructedtext?

How can I implement automatic multilevel list numbering in sphinx reStructuredText? Let's say there is a to-do list somewhere in the document: (here the numbering is manual) 1. Do something #1 1....
T4ASICK 's user avatar
0 votes
0 answers
38 views

How to make reStructuredText ASCII art that includes backslash (`\)`? [duplicate]

I would like to include some ASCII art in a doc-string. However, even inside literal blocks, Sphinx seems to interpret \ as the escape sequence. Is there a reStructuredText environment in which the ...
Paul Brodersen's user avatar
1 vote
3 answers
391 views

reStructuredText: Automatic table of contents for standalone .rst file

I'm a Markdown user but recently I came across reStructuredText and I wanted to take advantage of its features to create technical documents in pdf. I know this markup language is mainly used with ...
UzbeKistaN's user avatar
0 votes
2 answers
223 views

How to programmatically create doctrees in Sphinx?

I'm creating a Sphinx extension that generates a pretty huge number of RST files. Since I formally know the content of them, I'd like to gain time and space by directly writing the docutils, skipping ...
Oragon Efreet's user avatar
0 votes
1 answer
65 views

Create directive which wraps other directives inside

We are trying to create a directive which wraps other directives inside. The following example will show an example: Directives ========== .. service_card_wrapper:: .. service_card:: .. ...
allegoric's user avatar
0 votes
1 answer
245 views

Pages not showing on side menu

I am using Sphinx and ReStructuredText to create documentation, but even though all pages were created the same way, only 4 out of 8 are showing on the side menu. This is my table of contents: .. ...
Agatha Garcia's user avatar
1 vote
0 answers
131 views

Nested references in custom directive

As part of a custom directive I am trying to support nested references. I have re-worked the todo example to demonstrate what I am looking for. The complete repo is here: https://github.com/martynp/...
MartynP's user avatar
  • 11
2 votes
0 answers
116 views

How to create a new document in Sphinx/docutils by API?

I' writing a new extension for Sphinx as a domain offering multiple directives, roles and indices for the hardware description language VHDL. This extension shall be able to auto document language ...
Paebbels's user avatar
  • 15.7k
0 votes
1 answer
45 views

Parse raw rst string using nested_parse

I'm writing a sphinx extension that transforms a custom directive into a flat-table. From inside the .run(self) method, I build a complete flat-table declaration in pure .rst, and I'd like to feed ...
Arthur Attout's user avatar
0 votes
1 answer
60 views

Why does the docutils/Sphinx "include" directive represent a potential security hole?

The source of the claim is in the Docutils documentation, at https://docutils.sourceforge.io/docs/ref/rst/directives.html#include: Warning The "include" directive represents a potential ...
Yerushalmi's user avatar
0 votes
1 answer
121 views

Sphinx Using Domain Data/Indices

i was following the Tutorial for the “recipe” extension (https://www.sphinx-doc.org/en/master/development/tutorials/recipe.html). I am a little confused as the compiled html side doesn't show the ...
Jonas Sorgenfrei's user avatar
0 votes
0 answers
34 views

Custom sphinx directive fails when the content contains a nested glossary 'term' role

I have developed a sphinx extension for creating dependencies between different sections of a document. The primary application is plain text requirements management. The main object in the extension ...
danieleades's user avatar
1 vote
0 answers
42 views

Invoking other directives from my own bespoke directive

I'm making a extension for sphinx, which takes c code block, compiles it with arguments and stores the assembly/listing output to separate file. I take the c code block, the asm code block and the ...
Anton Krug's user avatar
  • 1,617
0 votes
0 answers
32 views

Combining replace and include in reStructuredText / Sphinx [duplicate]

I have been searching for a solution to this, but have just got even more confused! I have a use case in my documentation to replace many instances of a name for a piece of equipment. I had been using ...
Mark Lees's user avatar
2 votes
0 answers
168 views

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 ...
Jonas's user avatar
  • 56
0 votes
0 answers
77 views

Create document without source, based on parse sources

With a sphinx extension, can I create additional sphinx pages not related to a specific source file? source files: foo.xml bar.xml output files: foo.html bar.html wanted.html The wanted file would ...
Fab-B's user avatar
  • 41
1 vote
1 answer
53 views

Supress cross reference hyperlink using exclamation mark

Prefixing the link with an ! suppresses the creation of a reference (e.g. :ref:`!no link` will be simply rendered as no link): If you prefix the content with !, no reference/hyperlink will be created....
Stef's user avatar
  • 28.9k
1 vote
0 answers
271 views

Sphinx- Print in a rst file a custom string variable defined in conf.py

I am defining in conf.py a string variable X that I would like to print in a rst file. Here is what I did : In conf.py: X = "MY CUSTOM STRING" In the rst file: Using |X| But the html shows:...
dada's user avatar
  • 1,412
0 votes
0 answers
375 views

Error: couldn't find version that satisfied requirements docutils==0.16 and no matching distribution found for docutils

While I was installing requirements.txt using: pip install -r requirements.txt. I got this error WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after ...
Anu's user avatar
  • 1
2 votes
1 answer
400 views

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 ...
tony's user avatar
  • 896
1 vote
1 answer
5k views

docutils ERROR: Could not install packages due to an OSError: [Errno 2] No such file or directory

when I run pip show I get FileNotFoundError: [Errno 2] No such file or directory: '/[my_home] /.local/lib/python3.8/site-packages/docutils-0.16.dist-info/METADATA' and when I try to install docutils ...
jjrr's user avatar
  • 1,068
0 votes
0 answers
233 views

Sphinx can't generate link text as literal

With Markdown, I can simply: [`a link with monospace font`](https://www.example.com) a link with monospace font Note how the above line is properly rendered by SO's MD renderer: the link text is in ...
Leonardo's user avatar
  • 1,609
0 votes
1 answer
215 views

How to create an custom sphinx extention that works in latex

I created a super small extention to add the role "icon" in my doc. The idea is to write down the following : I'm a folder :icon:`fa fa-folder` I adapted some code find online and came up ...
Pierrick Rambaud's user avatar
3 votes
1 answer
599 views

Getting "Extension error (sphinx.environment.collectors.toctree)" when adding section nodes in Sphinx extension

I am trying to write a new Sphinx extension. A minimum example of an extension that does something similar to what I want is from docutils import nodes from docutils.parsers.rst import Directive ...
Milliron X's user avatar
  • 1,184
1 vote
1 answer
209 views

how to make a custom sphinx role that is also an external link?

I'm trying to extend Sphinx to have a new inline role called newcontrib. What it should do is take its content and (1) add some extra text to it, (2) make the text bold in the rendered output, and (3) ...
drammock's user avatar
  • 2,415
0 votes
1 answer
193 views

Extracting blocks of text from RST documents,files by :ref:?

I have a rst file SWAP.rst and i need to extract some specific data and put in a dictionary. the file looks like this: :baseID: SWAP_DF The current used for the force ... .. requirement::...
IlikeBlue LoL's user avatar
1 vote
0 answers
33 views

Transform reST list item for rst2html output

I have a reStructuredText document with todo list items: Vim === - ✓ (2021-11-05) RST Section text object (drop it in favor of env text object) Probably should be based on the output of ``:Toc`` ...
Maxim Kim's user avatar
  • 6,232
1 vote
1 answer
45 views

Link directives in Rst grammar

How can I link directive with :doi: or :arxiv: in Rst. I'm making a document with Rst, but when I try to link with arxiv, it shows broken link. What I tried is below but not working. <:doi:`10.1145/...
puhuk's user avatar
  • 474
3 votes
1 answer
407 views

How to parse Sphinx custom directive content to docutil nodes

I'm trying to create a custom directive called LicenceDirective which looks like it: .. licence: Some Software 3.0 :url: https://SomeSoftware.com/downloads :path: /licence_file CONTENT The ...
Oragon Efreet's user avatar
1 vote
0 answers
335 views

Using packages in sphinx latex yields "unknown environment "package"" error message

I would like to create a table using latex elements in my sphinx documentation. So far I have added the following lines to my conf.py: latex_engine = 'xelatex' latex_elements = { 'preamble': r''' ...
Yes's user avatar
  • 331
0 votes
1 answer
492 views

Creating a sphinx extension involving a directive that takes in arguments

I am relatively new to writing sphinx extensions and would like to create one that takes in a number of keywords that are provided alongside the directive name inside the rst document and replaces it ...
Yes's user avatar
  • 331
3 votes
0 answers
269 views

Creating a custom table generator as a sphinx extension

I would like to create a custom directive that functions similar to docutil's list-table element, where I provide a list of arguments afterwards and use them to render a html table with a custom ...
Yes's user avatar
  • 331
3 votes
0 answers
193 views

Accented characters in Sphinx headings [closed]

I want to include accented characters in a Sphinx heading such that I will see the following result: Finalé I have tried the following strategies: Use the unicode character directly such as: Finalé ==...
Jonathan's user avatar
  • 2,675
1 vote
1 answer
2k views

Docutils dependecy of Sphinx theme on readthedocs

I used to keep a project docs on readthedocs.io server. Here is the link CoFEA Initiative Since the 3rd of April, it looks a bit broken (e.g. the main logo is aligned to the left while it should be ...
Spike1991's user avatar
2 votes
2 answers
447 views

How do I unparse restructured text back into an rst file?

My question is a follow up to How to parse restructuredtext in python? where @mbdevpl provided code for parsing the file into a tree and doing some processing on the tree. I want to autoformat Python ...
user avatar
0 votes
1 answer
107 views

Exact docutils equivalent for :ref:

The following ReStructuredText contains the :ref: role, which is a Sphinx-extension: Read more in :ref:`section-target`. .. _section-target: Section Title ============= Text body. Where :ref:`...
MacFreek's user avatar
  • 3,246
0 votes
0 answers
112 views

Python Sphinx Validate and update schema

I'm using Sphinx to maintain docs on a project, I am generating a jsonschema document from a tool where all properties of objects are listed. Those objects properties are documented in rst files, I ...
Guillermo Ruffino's user avatar
1 vote
0 answers
460 views

How do I set a caption for my generated code block in sphinx

Currently I am using the following code to generate a code block and show some information in it. I'd like to set a caption like with the following rst directive. .. code-block:: python :caption: ...
spaceman_spiff's user avatar
1 vote
0 answers
52 views

SphinxDirective access to config._raw_config data

I need to do something very simple: Access the tag generated by the command line: $ sphinx-build -t <tag_name> Example: $ sphinx-build -t Foo Will create a dictionary entry in: sphinx.util....
natersoz's user avatar
  • 1,694
3 votes
2 answers
332 views

Generating labels for nodes of a custom directive

Using the Sphinx "TODO" Directive example I would like to reference the todo instances embedded within a .rst file. For example, if the .rst file content contains: .. todo:: foo .. todo:: ...
natersoz's user avatar
  • 1,694
0 votes
0 answers
62 views

What arguments to pass to inliner.parse() inside a custom role

I am defining my custom role that allows :ref: markups to be inside of it. The role is to be used as follows: myrole:`some_text |SUBS| more_text` A function replaces |SUBS| by :ref:`some_target` so ...
Hachem Yassine's user avatar
2 votes
1 answer
531 views

How do I make my sphinx directive add assets to _static folder?

I'm building a custom sphinx extension and Directive to render interactive charts on sphinx and ReadTheDocs. The actual data for a chart resides in a .json file. In a .rst document, including a chart ...
thclark's user avatar
  • 4,962
0 votes
1 answer
250 views

How to get inline code ending with spaces with docutils/sphinx?

The following rST directive doesn't support trailing spaces: :code:`foo ` Example: >>> from docutils import core >>> whole = core.publish_parts(""":code:`x `&...
nowox's user avatar
  • 26.6k
3 votes
1 answer
102 views

Docutils difference between text and rawsource in nodes.Text?

When creating new nodes such as nodes.title, one needs to provide two strings: rawsource text Often I see this: nodes.title('foobar', 'foobar', ids=[id]) Or sometime... nodes.target('', '') I don'...
nowox's user avatar
  • 26.6k