How to use Sphinx to document bash scripts?

Question

I just started to use Sphinx (sphinx-doc.org) to document a Python project. So far it works and I am able to doc and autodoc my Python code.

The project also contains a couple of bash scripts. I would like to use autodoc to document those bash scripts as well. I do not find a specific domain for bash scripts. So I guess one would have to use the Standard Domain?

How would you do this (if possible)? How do I have to configure index.rst and how do I have to use reStructuredText in the bash script?

Autodoc is for Python modules only. Sphinx has no similar facility for Bash scripts. — mzjn

Anthony Petrillo Anthony Petrillo · Accepted Answer · 2019-05-23T02:27:14

Here are the examples you requested. I'm using .rst for my source_suffix, but you can change that in your conf.py for your site. Notice, I named the bash file test.sh.rst to remind myself it is a bash file. Linux doesn't care what the file name is as long as you set the mod with chmod +x.

index.rst example:

.. _MyManual:

My Manual
===========================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   doc/doc
   bash/test.sh

Example test.sh.rst:

#!/bin/bash
: '

***********************
Example Bash
***********************

Using multi-line comment for larger comments. 

And use hash # to proceed code so it shows nicely in sphinx. Note the double 
:: at the end to give the proper formatting. 

'

# Initial code::

    mkdir tmp

# check_client::

   check_client()
   {
   # determine if this is being run on a client that is using git folder
   # check the parameter for the bash on CLI and if exist, use it
   echo HERE in client "$1" and "$parameter_1"
   if [[ "$parameter_1" = "" ]]; then
      client_directory=/
   else
      client_directory=/git
   fi
   }

# other code::

   parameter_1="$1"
   check_client
   echo the client is "$client_directory"

   read -p "pause " answer

How to use Sphinx to document bash scripts?

1 Answers