Как использовать Sphinx для документирования скриптов bash? - PullRequest
Новая
       7

Как использовать Sphinx для документирования скриптов bash?

0 голосов
/ 19 февраля 2019

Я только начал использовать Sphinx (sphinx-doc.org) для документирования проекта Python.Пока это работает, и я могу документировать и автоматически документировать свой код Python.

Проект также содержит несколько скриптов bash.Я хотел бы использовать autodoc для документирования этих скриптов bash.Я не нахожу конкретный домен для скриптов bash.Так что я думаю, что нужно использовать Стандартный домен ?

Как бы вы это сделали (если это возможно)?Как мне настроить index.rst и как использовать reStructuredText в скрипте bash?

1 Ответ

0 голосов
/ 23 мая 2019

Вот примеры, которые вы запросили.Я использую .rst для моего source_suffix, но вы можете изменить это в своем conf.py для своего сайта.Обратите внимание, я назвал bash-файл test.sh.rst, чтобы напомнить себе, что это bash-файл.Linux не волнует, какое имя файла, если вы установили мод с помощью 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
...