时间戳

首页 > 解决方案 > 如何使用 Sphinx 记录 bash 脚本？

bash - 如何使用 Sphinx 记录 bash 脚本？

问题描述

我刚开始使用 Sphinx (sphinx-doc.org) 来记录一个 Python 项目。到目前为止，它可以工作，我能够对我的 Python 代码进行 doc 和 autodoc。

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

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

标签： bashpython-sphinx

解决方案

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

index.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

推荐阅读