The :ref: role is a Sphinx extension to reStructuredText. It produces a internal reference to a section, and renders as the title of the referenced section.

For example:

Read more in :ref:`section-target`.

.. _section-target:

Section Title
=============
Text body.

Where

:ref:`section-target`

is parsed to the following doctree:

<reference internal="True" refid="section-target"><inline classes="std std-ref">Section Title</inline></reference>

which is typically rendered as <a href="#section-target">Section Title</a>, thus with name "Section Title" and hyperlink to "section-target".

Restbuilder should output "vanilla" reStructuredText, thus without Sphinx-specific roles or directives (as most non-Sphinx renderers don't know how to deal with them). So I'm looking for a docutils restructuredtext equivalent that produces the same (doctree) output.

So far, the closest I got was:

`Section Title <#section-target>`_

which resulted in:

<reference name="Section Title" refuri="#section-target">Section Title</reference>

That's close, but it defines a refuri, not a refid.

Regretfully, the documentation of the reference doctree is missing.

I've asked this question at https://stackoverflow.com/questions/66200071/exact-docutils-equivalent-for-ref, but have not received any useful response yet. So I'm currently accepting poor :ref: support, but raise the issue here, so we can track it, and hopefully will find a better solution in the future.

First of all, thanks for this extension !

I use restbuilder to generate a README.rst file that serves as the README of Github repository.
I have the following folder hierarchy :
documentation > source > README.rst
and when I build the documentation, I get a documentation > build > README.rst file that I later move to the root of my repository to serve as the main README.

I need to render the source/README.rst because it contains directives such as .. include and .. image.

For instance, I would like to display badges for my project, in my source README.rst I have :

.. image
   :target: https://thewebsitethathostsmybadge.com/myproject.svg

But I get the following error, with the associated stacktrace :

#   sphinx.ext.mathjax (1.8.3) from ~~~REPLACED~~~env37/lib/python3.7/site-packages/sphinx/ext/mathjax.py
#   alabaster (0.7.12) from ~~~REPLACED~~~env37/lib/python3.7/site-packages/alabaster/__init__.py
#   sphinx.ext.autodoc (1.8.3) from ~~~REPLACED~~~env37/lib/python3.7/site-packages/sphinx/ext/autodoc/__init__.py
#   sphinx.ext.doctest (1.8.3) from ~~~REPLACED~~~env37/lib/python3.7/site-packages/sphinx/ext/doctest.py
#   sphinxcontrib.restbuilder (unknown version) from ~~~REPLACED~~~env37/lib/python3.7/site-packages/sphinxcontrib/restbuilder.py
Traceback (most recent call last):
  File "~~~REPLACED~~~env37/lib/python3.7/site-packages/sphinx/cmd/build.py", line 304, in build_main
    app.build(args.force_all, filenames)
  File "~~~REPLACED~~~env37/lib/python3.7/site-packages/sphinx/application.py", line 341, in build
    self.builder.build_update()
  File "~~~REPLACED~~~env37/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 347, in build_update
    len(to_build))
  File "~~~REPLACED~~~env37/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 412, in build
    self.write(docnames, list(updated_docnames), method)
  File "~~~REPLACED~~~env37/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 593, in write
    self._write_serial(sorted(docnames))
  File "~~~REPLACED~~~env37/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 604, in _write_serial
    self.write_doc(docname, doctree)
  File "~~~REPLACED~~~env37/lib/python3.7/site-packages/sphinxcontrib/builders/rst.py", line 130, in write_doc
    self.writer.write(doctree, destination)
  File "~~~REPLACED~~~env37/lib/python3.7/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "~~~REPLACED~~~env37/lib/python3.7/site-packages/sphinxcontrib/writers/rst.py", line 40, in translate
    self.document.walkabout(visitor)
  File "~~~REPLACED~~~env37/lib/python3.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "~~~REPLACED~~~env37/lib/python3.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "~~~REPLACED~~~env37/lib/python3.7/site-packages/docutils/nodes.py", line 166, in walkabout
    visitor.dispatch_visit(self)
  File "~~~REPLACED~~~env37/lib/python3.7/site-packages/docutils/nodes.py", line 1882, in dispatch_visit
    return method(node)
  File "~~~REPLACED~~~env37/lib/python3.7/site-packages/sphinxcontrib/writers/rst.py", line 712, in visit_reference
    self.add_text('`%s <%s>`_' % (node['name'], node['refuri']))
  File "~~~REPLACED~~~env37/lib/python3.7/site-packages/docutils/nodes.py", line 567, in __getitem__
    return self.attributes[key]
KeyError: 'name'

Can someone help me out here ?

Hello,
I know this isn't an issue but I didn't know where to put it. There are a few things I'd like to discuss:

• Nested tables, and morerows/morecols support
• Wiki-like index as an option, I find myself adding this to a lot of my conf.py

def rst_file_transform(docname: str) -> str:
    docname = "Home" if docname == "index" else docname
    return f"{docname}.rst"


def rst_link_transform(docname: str) -> str:
    return "Home" if docname == "index" else docname

• _Sidebar option would also be really nice
• Document names as titles so it looks nicer on some wikis

But apart from tables, all the others are opinionated so it may be good to discuss. So would it be possible to enable discussions?

Hi,

I have a reproducible bug occurring when processing a Python file with a class docstring mentioning another class in the same file.

Here is an example Python file:

class class_one():
    """docstring of class_one. """


class class_two():
    """docstring of class two.

        Attributes:
            some_attribute (class_one): path to dicom file. Can be set directly.

    """

    some_attribute = class_one()

And my index.rst:

class_one
----------------

.. autoclass:: sphinx_bug.code.classes.class_one
    :members:
	
	
class_two
----------------

.. autoclass:: sphinx_bug.code.classes.class_two
    :members:

When I launch make rst I get:

Exception occurred:
  File "C:\Users\Claudio\miniconda3\envs\imaging\lib\site-packages\docutils\nodes.py", line 625, in __getitem__
    return self.attributes[key]
KeyError: 'name'
The full traceback has been saved in C:\Users\Claudio\AppData\Local\Temp\sphinx-err-npr86koc.log, if you want to report the issue to the developers.

I think this is a restbuilder issue because make html works (and class_one is correctly linked). The RST output works if I substitute some_attribute (class_one): with some_attribute (int):.

I am using:

• sphinxcontrib-restbuilder 0.2 (from conda)
• Sphinx version: 3.4.3
• Python version: 3.6.12 (CPython)
• Docutils version: 0.16 release
• Jinja2 version: 2.11.2

I am attaching the full log: sphinx-err-r16s30r_.log
Thank you!

Hi,

is there any plan to add support for sphinxcontrib.mermaid?

Currently, if I add restbuilder and mermaid in conf.py:

extensions = ['sphinxcontrib.restbuilder',
              'sphinxcontrib.mermaid']

And then add a diagram in a rst file:

This is a graph:

.. mermaid::

   graph LR
      id1[Item1] --> id2[Item 2];
      id2 --> id3[Item 3];

I get an NotImplementedError: Unknown node: mermaid.

Thanks in advance!

My environment:

Sphinx 4.2.0
sphinxcontrib-applehelp 1.0.2
sphinxcontrib-devhelp 1.0.2
sphinxcontrib-htmlhelp 2.0.0
sphinxcontrib-jsmath 1.0.1
sphinxcontrib-matlabdomain 0.12.0
sphinxcontrib-mermaid 0.7.1
sphinxcontrib-qthelp 1.0.3
sphinxcontrib-restbuilder 0.3

just a simple test

# index.rst
.. image:: _static/foo.png
.. figure:: _static/foo.png

seems to copy no images in the resulting rst build, and insert no image hyperlinks

I've seen a few forks (in particular https://github.com/davidfritzsche/sphinx-rst-builder/) that renamed sphinxcontrib.restbuilder to sphinx-rst-builder.

I think it's useful to be consistent, if only because to ensure that different forks don't diverge too much.

There are a few pros and cons to renaming. I'd appreciate if you have a look and voice your opinion in the comments bellow. (Either rename, keep, or don't care).

Pro renaming:

1. restbuilder is really a child module to sphinxcontrib. This means that files are somewhat scattered (e.g. in sphinxcontrib/writers/rst.py and sphinxcontrib/restbuider.py, along with files of other modules). It also makes it slightly harder to write tests for restbuilder: import restbuilder on it's own fails with an ImportException, and from sphinxcontrib import restbuilder will look for the installed files in site-packages/sphinxcontrib, not look in the directory you like to test. Sure this can be overcome, but it's not very clean. Child modules are mostly a legacy from when Sphinx code contributions used BitBucket instead of GitHub, and there doesn't seem a benefit.

2. It aligns with the https://github.com/davidfritzsche/sphinx-rst-builder/ fork, that seem to be the most current as the time.

Con renaming:

1. It's a backward incompatible change.

2. Most other Sphinx extensions still seem to use the sphinxcontrib namespace. (Note: I only checked those in the sphinxcontrib GitHub organisation, which likely have that for historic reasons).

It would be nice if it could support math expressions. For example . . .

.. math::

   E = m c^2

It should generate the image and reference the math image in the rst

Hi, I have been having a difficult to interpret error message when compiling a project:

writing output... [100%] index
Exception occurred:
  File "C:\ProgramData\Miniconda3\envs\sphinx\lib\site-packages\docutils\nodes.py", line 652, in __getitem__
    return self.attributes[key]
KeyError: 'name'

I was able to track it down to this very minimalistic RST source file:

This is a link: http://www.google.com

This source fail fails to compile. However, this one works:

This is a link: www.google.com

I should also mention that the standard HTML compiler works.in both cases.

Hi,
I just realized that the newest fixes are not available to the installation via pip.
For example this deec25c

Could we upload the latest version of this to pip ?
Thanks

I just received a message from @chrisjbremner asking me to push a Python3 compatible version to Pypi. Sure can do, I just have to look into it, since it has been a while since I wrote this code. Will probably take me 1 or 2 weeks due to some work deadlines.

But since there is some interest, I'm happy to bring it in a state where others can more easily use it.

That brings me to another point -- I like to move this forward, but reality is that is not very high priority for me. So, if there are other people willing to maintain this project, now would be a good time to step forward!

If none steps forward, I'm happy to do it in the background, but I think this project may need a bit more love (and some more unit tests) :)

The only recent contribution is a fork by @gnidan, but perhaps others are interested. Let me know.

hi,
I am translating rst file to have the sources translated and displayed in the search results excerpts.
is it technically possible to implement the row/col spanning cells?

Exception occurred:
File "/home/samir/.local/lib/python2.7/site-packages/sphinxcontrib/writers/rst.py", line 385, in visit_entry
raise NotImplementedError('Column or row spanning cells are '
NotImplementedError: Column or row spanning cells are not implemented.
The full traceback has been saved in /tmp/sphinx-err-dPxcAk.log, if you want to report the issue to the developers.

Comparing this repo with davidfritzsche's: the indentation of bullet lists differ by a space.

With input like this:

Unreleased
----------

- ``coverage combine`` has a new option, ``--keep`` to keep the original data
  files after combining them.  The default is still to delete the files after
  they have been combined.  This was requested in `issue 1108`_ and implemented
  in `pull request 1110`_.  Thanks, Éric Larivière.

.. _issue 1108: https://github.com/nedbat/coveragepy/issues/1108
.. _pull request 1110: https://github.com/nedbat/coveragepy/pull/1110

davidfritzsche produces:

Unreleased
==========

* ``coverage combine`` has a new option, ``--keep`` to keep the original data
  files after combining them.  The default is still to delete the files after
  they have been combined.  This was requested in `issue 1108 <https://github.com/nedbat/coveragepy/issues/1108>`_ and implemented
  in `pull request 1110 <https://github.com/nedbat/coveragepy/pull/1110>`_.  Thanks, Éric Larivière.

This repo produces:

Unreleased
==========

* ``coverage combine`` has a new option, ``--keep`` to keep the
   original data files after combining them.  The default is still to
   delete the files after they have been combined.  This was requested
   in `issue 1108 <https://github.com/nedbat/coveragepy/issues/1108>`_
   and implemented in `pull request 1110
   <https://github.com/nedbat/coveragepy/pull/1110>`_.  Thanks, Éric
   Larivière.

I use pandoc to convert this to markdown, with a command like:

pandoc -frst -tmarkdown_strict --atx-headers --wrap=none /tmp/converted.rst

The good output gets converted to:

## Unreleased

-   `coverage combine` has a new option, `--keep` to keep the original data files after combining them. The default is still to delete the files after they have been combined. This was requested in [issue 1108](https://github.com/nedbat/coveragepy/issues/1108) and implemented in [pull request 1110](https://github.com/nedbat/coveragepy/pull/1110). Thanks, Éric Larivière.

Which renders accurately as Markdown:

Unreleased

• coverage combine has a new option, --keep to keep the original data files after combining them. The default is still to delete the files after they have been combined. This was requested in issue 1108 and implemented in pull request 1110. Thanks, Éric Larivière.

This repo's output gets converted to:

## Unreleased

-   `coverage combine` has a new option, `--keep` to keep the
    original data files after combining them. The default is still to delete the files after they have been combined. This was requested in [issue 1108](https://github.com/nedbat/coveragepy/issues/1108) and implemented in [pull request 1110](https://github.com/nedbat/coveragepy/pull/1110). Thanks, Éric Larivière.

which does not render correctly as Markdown:

Unreleased

• coverage combine has a new option, --keep to keep the
  original data files after combining them. The default is still to delete the files after they have been combined. This was requested in issue 1108 and implemented in pull request 1110. Thanks, Éric Larivière.

Hello, using the rest extension to output the content from https://github.com/odoo/documentation-user, I get rst outputs with wrong nested list. For instance, for _build/rst/accounting.rst I would get something like

Invoicing and Accounting
************************

*  Overview
   *  Main Concepts
      *  `The Accounting behind Odoo
         <accounting/overview/main_concepts/in_odoo.rst>`_
      *  `Accounting Memento For Entrepreneurs (US GAAP)
         <accounting/overview/main_concepts/memento.rst>`_
   *  Getting Started
      *  `Initial setup of Odoo Accounting and Odoo Invoicing
         <accounting/overview/getting_started/setup.rst>`_
      *  `Chart of Accounts
         <accounting/overview/getting_started/chart_of_accounts.rst>`_
   *  Process overview
      *  `From Customer Invoice to Payments Collection
         <accounting/overview/process_overview/customer_invoice.rst>`_
      *  `From Vendor Bill to Payment
         <accounting/overview/process_overview/supplier_bill.rst>`_
*  Account Receivables
   *  Customer Invoices
      *  `Overview of the invoicing process
         <accounting/receivables/customer_invoices/overview.rst>`_
      *  `Offer cash discounts
         <accounting/receivables/customer_invoices/cash_discounts.rst>`_

The problem is - unless I'm wrong - nested lists should have extra line breaks to reflect the proper structure, like instead:

Invoicing and Accounting
************************

*  Overview

   *  Main Concepts

      *  `The Accounting behind Odoo
         <accounting/overview/main_concepts/in_odoo.rst>`_
      *  `Accounting Memento For Entrepreneurs (US GAAP)
         <accounting/overview/main_concepts/memento.rst>`_

   *  Getting Started

      *  `Initial setup of Odoo Accounting and Odoo Invoicing
         <accounting/overview/getting_started/setup.rst>`_
      *  `Chart of Accounts
         <accounting/overview/getting_started/chart_of_accounts.rst>`_

   *  Process overview

      *  `From Customer Invoice to Payments Collection
         <accounting/overview/process_overview/customer_invoice.rst>`_
      *  `From Vendor Bill to Payment
         <accounting/overview/process_overview/supplier_bill.rst>`_

*  Account Receivables

   *  Customer Invoices

      *  `Overview of the invoicing process
         <accounting/receivables/customer_invoices/overview.rst>`_
      *  `Offer cash discounts
         <accounting/receivables/customer_invoices/cash_discounts.rst>`_

At least that's what I could check on http://rst.ninjs.org

Also if you want to try to compile https://github.com/odoo/documentation-user, yourself, I had to comment the line 404 ´self.log_message('Column or row spanning cells are not implemented.')´ and replace it by pass, because there seem to be no such log_message method or not anymore.
sphinxcontrib/writers/rst.py

In commits 24c637c by @bfabio and 55233c9 by @davidfritzsche improvements were made to preserve code blocks.

These improvements should be backported to this repository.

Requested actions:

• Add a test suite with examples, e.g. the examples in docs/examples/examples.rst.
• Add all changes by @bfabio
• Selectively add improvements by @davidfritzsche (since that commit also included some other minor changes)
• Always preserve code block flags, if possible (so there is no need for a rst_preserve_code_black_flags configuration parameter. If this is not possible, try to find a solution compatible with 55233c9.

I'm trying to package your module as an rpm package. So I'm using the typical PEP517 based build, install and test cycle used on building packages from non-root account.

• python3 -sBm build -w --no-isolation
• because I'm calling build with --no-isolation I'm using during all processes only locally installed modules
• install .whl file in </install/prefix>
• run pytest with PYTHONPATH pointing to sitearch and sitelib inside </install/prefix>

There are three (minor) potential problems with line number in code blocks. I list them here for reference.

1. Github does not display a code-block with linenos parameter. (See code-block-linenos test file). It does show code-block without linenos parameter. (See code-block test file), and also shows code directive with number-lines parameter. (See code-number-lines test file). Since restbuilder outputs a code directive, this should work.
2. If you are still using Sphinx 1.x, and use code directive with number-lines parameter, Sphinx renders the numbers inline, and the number-lines is dropped. Your formatter may not render the line numbers as you prefer. If this is an issue, upgrade to Sphinx 2 or higher.
3. Somewhat related: If you are still using Sphinx 1.x, you cannot use a code-block without language (e.g. .. code-block:: instead of .. code-block:: python). This is a limitation in Sphinx 1.x, and can not be circumvented. Either upgrade to Sphinx 2 or higher, use a plain block literal (the :: construct), or use the .. code:: directive.

It would be great if this repo and https://github.com/davidfritzsche/sphinx-rst-builder could come back together. The other repo is distributed on PyPI, but doesn't have issues enabled. The two repos have diverged, but only a little bit.
@davidfritzsche what do you say?

The following bits are snipped a few different ways. See links for actual text. I am no reStructuredText expert so hopefully my terms aren't too incorrect, but it seems that while the substitution reference does get processed enough to result in the substitution definition's target being presented as the link, it does not process the definition's image.

https://github.com/altendky/qtrio/blob/eddc9446fda97567dd4e44971ff088bd0380743b/docs/source/README.rst

|documentation badge|
<snip>
.. _documentation: https://qtrio.readthedocs.io
.. |documentation badge| image:: https://img.shields.io/badge/docs-read%20now-blue.svg?color=royalblue&logo=Read-the-Docs&logoColor=whitesmoke
   :target: `documentation`_
   :alt: Documentation

becomes
https://github.com/altendky/qtrio/blame/eddc9446fda97567dd4e44971ff088bd0380743b/README.rst#L9-L12

`documentation <https://qtrio.readthedocs.io>`_   

The full scenario is that I am trying to render my .rst readme including .. literalinclude:: as well as badge images since GitHub won't process literalincludes.

altendky/qtrio#233

.rst result as rendered on GitHub.

.html result as rendered on Read the Docs.

There is an important difference between this repo and davidfritzsche's: with his, all links are explicit.

This in my source .rst file:

see :ref:`whatsnew5x`.

becomes this with davidfritzsche's fork:

see `Major changes in 5.0 <whatsnew5x.rst#whatsnew5x>`_.

With this repo, it becomes:

see `Major changes in 5.0`_.

I'm using restbuilder to produce .rst files that pandoc can convert to markdown files. These implicit references aren't resolvable by pandoc. Is there an option I can use with this repo to get fully resolved links?