如何使用 Sphinx 记录 bash 脚本？

Question

我刚刚开始使用 Sphinx (sphinx-doc.org) 来记录 Python 项目。到目前为止，它有效，我能够记录和自动记录我的 Python 代码。

该项目还包含几个 bash 脚本。我也想使用 autodoc 来记录这些 bash 脚本。我没有找到 bash 脚本的特定域。所以我想人们必须使用标准域？

你会怎么做（如果可能的话）？我必须如何配置index.rst以及如何在bash脚本中使用reStructuredText？

Answer 1

以下是您要求的示例。我在我的 .rst 中使用 .rst source_suffix，但您可以在您的站点的 conf.py 中更改它。请注意，我将 bash 文件命名为 test.sh.rst 以提醒自己这是一个 bash 文件。Linux 并不关心文件名是什么，只要你用chmod +x.

索引.rst 示例：

.. _MyManual:

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

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

   doc/doc
   bash/test.sh

示例 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