search

sphinx-contrib / restbuilder

A Sphinx builder/writer to output reStructuredText (rst) files
BSD 2-Clause "Simplified" License
31 stars 27 forks source link

Line numbers in code blocks #22

Closed macfreek closed 3 years ago

macfreek commented 3 years ago

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.
macfreek commented 3 years ago

Given that there are reasonable work-around for all three issues, I will close this as a wontfix. If you feel one of these should be fixed, feel free to propose a solution and reopen the issue.

For the first issue, you may want to followup on the (now outdated) bug report I posted at the Github community.