code-blocks.txt

.. meta::
   :robots: noindex, nosnippet 

=============
Code Examples
=============

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

Snooty supports the following directives for code samples:

- ``code-block``
- ``io-code-block``
- ``literalinclude``

These directives feature a monospace font and syntax highlighting that makes
source code easier to interpret.

Code Blocks
-----------

The ``code-block`` directive formats a code sample with the following options.

Syntax
~~~~~~

.. code-block::

   .. code-block:: <language>
      :copyable: <boolean>
      :emphasize-lines: <line numbers>
      :linenos:
      :caption: <caption text>
      :source: <url>

      <code sample>

Options
~~~~~~~

All of the following options are optional.

.. list-table::

   * - ``<language>``
     - Language to use for syntax highlighting. 
       
       For a complete list of supported languages, see the
       `leafygreen-ui GitHub repository. <https://github.com/mongodb/leafygreen-ui/blob/main/packages/code/src/languages.ts>`__

       **Default:** None
 
   * - ``:copyable: <boolean>``
     - Option that indicates whether to show the :guilabel:`copy icon`.

       **Default:** ``true``

   * - ``:emphasize-lines: <line number>``
     - Lines to highlight. You can specify a range 
       of line numbers, individual line numbers, or both.

       **Default:** None

   * - ``:linenos:``
     - Option that indicates whether to show line numbers.

       **Default:** None
  
   * - ``:caption: <caption text>``
     - Brief description.

       **Default:** None 

   * - ``:source: <url>``
     - Option that indicates whether to show the :guilabel:`source icon` and
       :guilabel:`View full source` tooltip.
       
       This icon is hidden if the ``copyable`` option is set to ``false``.
       
       **Default:** None

Example 1
~~~~~~~~~

.. code-block::
   
   .. code-block:: python
      :linenos:
      :copyable: true
      :emphasize-lines: 1, 4-5
      :caption: An example Python code block

      print("Hello Docs team!") 
      print("This is Python code...") 
      print("...inside a code-block.")
      print("The line numbers are over here <-")
      print("And the copy icon is over there ->")

The previous ``code-block`` directive creates the following output:

.. code-block:: python
   :linenos:
   :copyable: true
   :emphasize-lines: 1, 4-5
   :caption: An example Python code block

   print("Hello Docs team!") 
   print("This is Python code...") 
   print("...inside a code-block.")
   print("The line numbers are over here <-")
   print("And the copy icon is over there ->")

Example 2
~~~~~~~~~

.. code-block::
   
   .. code-block:: python
      :source: https://github.com/mongodb/docs-ecosystem/blob/36f9cc7260a246d47cb05ac35276a2c92734b028/conf.py#L120

      html_theme = sconf.theme.name
      html_theme_path = [os.path.join(conf.paths.buildsystem, 'themes')]
      html_title = conf.project.title
      htmlhelp_basename = 'MongoDBdoc'

The previous ``code-block`` directive creates the following output:

.. code-block:: python
   :source: https://github.com/mongodb/docs-ecosystem/blob/36f9cc7260a246d47cb05ac35276a2c92734b028/conf.py#L120

   html_theme = sconf.theme.name
   html_theme_path = [os.path.join(conf.paths.buildsystem, 'themes')]
   html_title = conf.project.title
   htmlhelp_basename = 'MongoDBdoc'

I/O Code Blocks
---------------

The ``io-code-block`` directive formats a code sample and
includes an expandable code block for the output and a button to
toggle its visibility.

Syntax
~~~~~~

.. code-block::

   .. io-code-block::
      :copyable: <boolean>
      :caption: <caption text>
      :source: <url>
      
      .. input::
         :language: <input language>
         :emphasize-lines: <line numbers>
         :linenos:

         <input code>

      .. output::
         :language: <output language>
         :emphasize-lines: <line numbers>
         :linenos:
         :visible: <boolean>

         <output code>

Options
~~~~~~~

All of the following options are optional.

.. list-table::

   * - ``:copyable: <boolean>``
     -  Option that indicates whether to show the :guilabel:`copy icon` for the input
        code.
   
        **Default:** ``false``
   
   * - ``:language:``
     - Language to use for syntax highlighting. You can specify
       different languages for the input and output code. 
       
       For a complete list of supported languages, see the
       `leafygreen-ui GitHub repository. <https://github.com/mongodb/leafygreen-ui/blob/main/packages/code/src/languages.ts>`__

       **Default:** None

   * - ``:linenos:``
     - Option that indicates whether to show line numbers.

       **Default:** None

   * - ``:emphasize-lines: <line number>``
     - Lines to highlight. You can specify a range 
       of line numbers, individual line numbers, or both.

       **Default:** None
   
   * - ``:visible: <boolean>``
     - Option that indicates whether the output code is initially visible. If ``false``,
       the user must click a button to see the output.

       **Default:** ``true``

   * - ``:caption: <caption text>``
     - Brief description.

       **Default:** None

   * - ``:source: <url>``
     - Option that indicates whether to show the :guilabel:`source icon` and
       :guilabel:`View full source` tooltip.
       
       This icon is hidden if the ``copyable`` option is set to ``false``.
       
       **Default:** None

Example 1
~~~~~~~~~

.. code-block::

   .. io-code-block::
      :copyable: true
      :caption: An example Python code block with output

      .. input::
         :language: python
         :emphasize-lines: 1
         :linenos:

         print("Hello Docs team!") 
         print("This is Python code...") 
         print("...inside an io-code-block.")

      .. output::
         :language: shell
         :emphasize-lines: 1
         :linenos:
         :visible: false

         "Hello Docs team!"
         "This is Python code..."
         "...inside an io-code-block."

.. io-code-block::
   :copyable: true
   :caption: An example Python code block with output

   .. input::
      :language: python
      :emphasize-lines: 1
      :linenos:

      print("Hello Docs team!") 
      print("This is Python code...") 
      print("...inside an io-code-block.")

   .. output::
      :language: shell
      :emphasize-lines: 1
      :linenos:

      "Hello Docs team!"
      "This is Python code..."
      "...inside an io-code-block."

Example 2
~~~~~~~~~

.. code-block::
   
   .. io-code-block::
      :source: https://github.com/mongodb/docs-node/blob/0cf95d4eac536ed0ae1a2085948dd98f24ac48af/source/quick-reference.txt#L473
      :copyable: true

      .. input::
         :language: javascript
         
         coll.find({ $text: { $search: 'zissou' } });

      .. output::
         :language: javascript

         [
             { title: 'The Life Aquatic with Steve Zissou', ... }
         ]

The previous ``io-code-block`` directive creates the following output:

.. io-code-block::
   :source: https://github.com/mongodb/docs-node/blob/0cf95d4eac536ed0ae1a2085948dd98f24ac48af/source/quick-reference.txt#L473
   :copyable: true

   .. input::
      :language: javascript
         
      coll.find({ $text: { $search: 'zissou' } });

   .. output::
      :language: javascript

      [
          { title: 'The Life Aquatic with Steve Zissou', ... }
      ]

Literal Includes
----------------

The ``literalinclude`` directive includes and formats a code example from another file.
You can specify the comments or other lines of code on which to start and end the example.
This directive allows you to maintain the code in a separate single file and display the
same code example in multiple places.

.. note::  include vs. literalinclude

    Use the ``literalinclude`` directive to include a code file in the docs.
    Use the ``include`` directive to include an ``rst`` file in the docs.

Syntax
~~~~~~

.. code-block::

   .. literalinclude:: <file path>
      :language: <language>
      :copyable: <boolean>
      :start-after: <line of code>
      :end-before: <line of code>
      :linenos:
      :lineno-start: <line number>
      :emphasize-lines: <line numbers>
      :caption: <caption>
      :dedent: <number>

Options
~~~~~~~

.. list-table::

   * - ``<file path>``
     - **Required.** Path to the file in the repository that contains the code to show.

       **Default:** None

   * - ``:language: <language>``
     - Language to use for syntax highlighting. 
       
       For a complete list of supported languages, see the
       `leafygreen-ui GitHub repository. <https://github.com/mongodb/leafygreen-ui/blob/main/packages/code/src/languages.ts>`__

       **Default:** None
 
   * - ``:copyable: <boolean>``
     - Option that indicates whether to show the :guilabel:`copy icon`.

       **Default:** ``true``

   * - ``:start-after: <line of code>``
     - Line of code before the first line to include in the sample.

       You can use a comment to mark the point where the ``literalinclude`` directive
       starts including code. If you do, omit the comment marker (``#`` or ``//``) from
       the attribute value.
       
       By using comments, you can unambiguously
       specify the start of the code example, regardless of how many examples you're
       including from the file. You also won't need to update the directive if the
       extracted code changes.

       **Default:** Beginning of file
   
   * - ``:end-before: <line of code>``
     - Line of code after the last line to include in the sample.

       You can use a comment to mark the point where the ``literalinclude`` directive
       stops including code. If you do, you can omit the comment marker (``#`` or ``//``)
       from the attribute value.
       
       By using comments, you can unambiguously
       specify the end of the code sample, regardless of how many examples you're
       including from the file. You also won't need to update the directive if the
       extracted code changes.

       **Default:** End of file

   * - ``:linenos:``
     - Option that indicates whether to show line numbers.

       **Default:** None
 
   * - ``:lineno-start:``
     - Number of the line at which to start showing line numbers. This option requires the
       ``:linenos:`` option.

       **Default:** 1

   * - ``:emphasize-lines: <line number>``
     - Lines to highlight. You can specify a range 
       of line numbers, individual line numbers, or both.

       **Default:** None
 
   * - ``:caption: <caption text>``
     - Brief description.

       **Default:** None

   * - ``:dedent: <number of spaces>``
     - Number of spaces to remove from the beginning of each line of code.
       Use this option if the code to show is indented in the code file.

       **Default:** None 

Example 1
~~~~~~~~~

Suppose you want to include samples from the following Python file in a documentation page:

.. literalinclude:: /includes/python-sample.py
   :language: python

The following ``literalinclude`` directive starts with the first line of the file and
ends before the line that reads ``print("...but this line won't.")``: 

.. code-block::
 
   .. literalinclude:: /includes/python-sample.py
      :copyable: false
      :end-before: print("...but this line won't.")
      :caption: Sample Python code from another file
  
The previous ``literalinclude`` directive creates the following output:

.. literalinclude:: /includes/python-sample.py
   :copyable: false
   :end-before: print("...but this line won't.")
   :caption: Sample Python code from another file

Example 
~~~~~~~~~

In the Python file in the previous example, the code inside ``sample_function()`` is
indented two spaces. The following ``literalinclude`` directive uses the ``:dedent:``
option to remove these spaces:

.. code-block::

   .. literalinclude:: /includes/python-sample.py
      :start-after: start-function-sample
      :end-before: end-function-sample
      :linenos:
      :lineno-start: 9 
      :dedent: 2

The previous directive creates the following output:


.. literalinclude:: /includes/python-sample.py
   :start-after: start-function-sample
   :end-before: end-function-sample
   :linenos:
   :lineno-start: 9 
   :dedent: 2