docutils-users

[Docutils-users] Is there a plan to integrate fenced code blocks in rst?

[Gökçe A. <goe...@th...>]

I use rst heavily for my documents and slides for teaching which in turn 
include many code blocks. Is it possible to use code blocks in rst 
without indenting them, e.g., like *fenced code blocks*?

The reason is, it is cumbersome to copy and paste indented code blocks. 
There is an extension for Sphinx for this purpose [1]. Is there a plan 
to integrate fenced code blocks in rst?

I am not subscribed and would be happy if you could CC me.

[1] https://sphinx-codefence.readthedocs.io/

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

[Alan G. I. <ala...@gm...>]

Why copy/paste at all when you can just ``include`` code?
Alan Isaac (who is just another user)


On 12/5/2020 5:15 AM, Gökçe Aydos wrote:
> I use rst heavily for my documents and slides for teaching which in turn include many code blocks. Is it possible to use code blocks in rst without indenting 
> them, e.g., like *fenced code blocks*?
> 
> The reason is, it is cumbersome to copy and paste indented code blocks. There is an extension for Sphinx for this purpose [1]. Is there a plan to integrate 
> fenced code blocks in rst?

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

[Gökçe A. <goe...@th...>]

On 06/12/2020 20:34, Alan G. Isaac wrote:
> Why copy/paste at all when you can just ``include`` code?

Thanks, that is a good idea for longer code Alan!

My case is different. For example in one document I have about 50 code 
blocks, which are about 2 to 8 lines long. Creating 50 files for this 
purpose would be very inconvenient.

When I copy code from the rendered version then it's no problem, but 
copying from the rst source is very error-prone due to the indentation, 
e.g.,:

code:: sh

   cat > file <<EOF
     4spaces here instead of 2
   and EOF does not work
   EOF

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

[Marcelo H. <mar...@gm...>]

El dom, 6 dic 2020 a las 17:02, Gökçe Aydos (<goe...@th...>)
escribió:


> My case is different. For example in one document I have about 50 code
> blocks, which are about 2 to 8 lines long. Creating 50 files for this
> purpose would be very inconvenient.
>

You don't need to do that. The include directive accepts the "start-line"
and "end-line" parameters which allow you to take information from a
separate file. Also, if you edit the file frequently, you can add delimiter
comments to the sections of code and use the :start-after: and :end-before:
parameters.

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

[Guenter M. <mi...@us...>]

On 2020-12-06, Gökçe Aydos wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> On 06/12/2020 20:34, Alan G. Isaac wrote:
>> Why copy/paste at all when you can just ``include`` code?

> Thanks, that is a good idea for longer code Alan!

> My case is different. For example in one document I have about 50 code 
> blocks, which are about 2 to 8 lines long. Creating 50 files for this 
> purpose would be very inconvenient.


> When I copy code from the rendered version then it's no problem, but 
> copying from the rst source is very error-prone due to the indentation, 
> e.g.,:

> code:: sh

>    cat > file <<EOF
>      4spaces here instead of 2
>    and EOF does not work
>    EOF

When working with reStructuredText, I find myself using the "rectangualar
blocks" feature of my text editor a lot.

However, your example looks a lot like a use case for `PyLit`_, where you
can convert easily in both directions between a "text" and "code" version
of a document, e.g.,

text::

  # Options for HTML output
  # -----------------------
  #
  # The style sheet to use for HTML and HTML Help pages. A file of that name
  # must exist either in Sphinx' static/ path, or in one of the custom paths
  # given in html_static_path::
  
  html_style = 'pylit-sphinx.css'
  # html_style = 'sphinxdoc.css'
  
  # Options to the theme, like a sidebar that is visible even when
  # scrolling (TODO: how to get this to work (maybe just update Spinx)?)::
  
  #html_theme_options = {'stickysidebar': 'true'}
  
  # The name for this set of Sphinx documents.  If None, it defaults to
  # "<project> v<release> documentation". ::
  
  html_title = "PyLit"
  
  # A shorter title for the navigation bar.  Default is the same as html_title.
  # ::
  
  html_short_title = "Home"

code::
  
  Options for HTML output
  -----------------------
  
  The style sheet to use for HTML and HTML Help pages. A file of that name
  must exist either in Sphinx' static/ path, or in one of the custom paths
  given in html_static_path::
  
    html_style = 'pylit-sphinx.css'
    # html_style = 'sphinxdoc.css'
    
  Options to the theme, like a sidebar that is visible even when
  scrolling (TODO: how to get this to work (maybe just update Spinx)?)::
  
    #html_theme_options = {'stickysidebar': 'true'}
    
  The name for this set of Sphinx documents.  If None, it defaults to
  "<project> v<release> documentation". ::
  
    html_title = "PyLit"
    
  A shorter title for the navigation bar.  Default is the same as html_title.
  ::
  
    html_short_title = "Home"


Günter


.. _Pylit: https://pypi.org/project/pylit/

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

[Guenter M. <mi...@us...>]

On 2020-12-05, Gökçe Aydos wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> I use rst heavily for my documents and slides for teaching which in turn 
> include many code blocks. Is it possible to use code blocks in rst 
> without indenting them, e.g., like *fenced code blocks*?

> The reason is, it is cumbersome to copy and paste indented code blocks. 
> There is an extension for Sphinx for this purpose [1]. Is there a plan 
> to integrate fenced code blocks in rst?

There are currently no plans to do that and I do not expect this to come
easily or anytime soon. (You many, however, file (or add to) an enhancment
ticket at the issue tracker 
https://sourceforge.net/p/docutils/feature-requests/.)

One problem with [1] is a possible clash with section underlining like ::

  Tip
  ```
  
  In rST, section underlines may use any of the characters
  ``= - ` : ' " ~ ^ _ * + # < >``.
  
The development version 0.17b.dev in the repository has experimental support
for Markdown sources, where fenced literal blocks are part of the
format specification.

Günter


> [1] https://sphinx-codefence.readthedocs.io/

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

[Alan G. I. <ala...@gm...>]

The include directive allows literal inclusion of fragments:
https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment

hth, Alan Isaac


On 12/6/2020 3:01 PM, Gökçe Aydos wrote:
> Thanks, that is a good idea for longer code Alan!
> 
> My case is different. For example in one document I have about 50 code blocks, which are about 2 to 8 lines long. Creating 50 files for this purpose would be 
> very inconvenient.


 > On 06/12/2020 20:34, Alan G. Isaac wrote:
 >> Why copy/paste at all when you can just ``include`` code?
 >

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

[Gökçe A. <goe...@th...>]

On 07/12/2020 18:07, Alan G. Isaac wrote:
> The include directive allows literal inclusion of fragments:

Very good idea if I have a single file where I get my code blocks.

I have many code snippets which are build on top of each other, or are 
independent.

I could put all the code fragments in a single file and address them 
using the include directive. Then I would have to find a way to 
synchronize the two views. I find this still inconvenient compared to a 
single file solution.

Does someone have a better solution?

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

[Guenter M. <mi...@us...>]

On 2020-12-07, Gökçe Aydos wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> On 07/12/2020 18:07, Alan G. Isaac wrote:
>> The include directive allows literal inclusion of fragments:

> Very good idea if I have a single file where I get my code blocks.

> I have many code snippets which are build on top of each other, or are 
> independent.

> I could put all the code fragments in a single file and address them 
> using the include directive. Then I would have to find a way to 
> synchronize the two views. I find this still inconvenient compared to a 
> single file solution.

> Does someone have a better solution?

* PyLit__, the bidirectional text/code converter.

* An editor with support for rectangular regions and/or (un)indenting.

* Markdown (with Docutils version 0.17b.dev).

Günter

__ https://pypi.org/project/pylit/