ShellDoc is a tool for generating reStructuredText formatted documentation
from shell scripts, or any programming language that uses the
to denote comments. This generally makes it useful as a documentation generator
for languages that do not have documentation generators.
While any language using
# as a comment character can be used with
ShellDoc, keep in mind that it is specifically tailored for shell scripting
languages in the sh family.
ShellDoc is loosely inspired by the PowerShell documentation format, and is written in Python 3. ShellDoc has no dependencies beyond the Python 3 standard library.
- Language-agnostic; ShellDoc does not attempt to parse or understand the documented source code at all - only lines that begin with # are even considered by ShellDoc.
- Standalone .rst output can be used with Sphinx, or with rst2pdf.
- Documentation syntax is human-readable, and every easy to learn.
- Stream-oriented, single-pass design make ShellDoc safe to use in
- HINT: use
--input=/dev/stdinto accept input from pipes.
- HINT: use
ShellDoc understands two types of documentation: documentation for scripts, and documentation for functions. Either or both can be present in a single input file. Documentation is broken into logical segments, which are further broken down into sections.
Script-level documentation begins with the following line (segment opening):
Function-level documentation begins with the following line (segment opening):
# .DOCUMENTS functionname
Both types of segments end with:
All commented lines in the input between a segment opening and it's associated
.ENDOC constitute a segment.
Note that all leading whitespace to the
# symbol, the
#, and the
first character after it are stripped. For example, consider this input:
# some text # some more text #one more line of text
This would produce the output:
some text some more text ne more line of text
Within a segment, there are a number of valid sections. Sections begin with a line of the format:
And end either at
.ENDOC or when the next section begins.
The following section types are valid for script-level segments:
The following section types are valid for function-level segments:
Aside from segment openings,
.ENDOC statements, and section openings, all
other lines of input that begin with
# and are part of a segment/section
are passed through unmodified (except for leading and trailing whitespace being
Note that empty commented lines are preserved, for example:
# some words # # #
results in the output
some words followed by 3 blank lines.
Runs of empty lines (containing only whitespace) imply a single blank line in the output. For example:
# paragraph 1 # # paragraph 2
Would result in the output:
paragraph 1 paragraph 2
All sections except for
.SYNTAX are passed directly through to the output
without modification, the Syntax section is a bit different. Namely, it is
rendered as a reStructuredText pre-formatted code block (i.e. it is preceded by
::, and each line in the Syntax section is indented by four spaces).
This design decision was made because there are many common plain-text styles and formats that do not translate well to reST.
usage: shelldoc [-h] --input INPUT [--output OUTPUT | --prefix PREFIX] [--doctitle DOCTITLE | --titledepth TITLEDEPTH] [--notoc] [--notitle] A tool for documenting shell scripts optional arguments: -h, --help show this help message and exit --input INPUT, -i INPUT Input file to process --output OUTPUT, -o OUTPUT Output file for generated documentation, stdout by default. --prefix PREFIX, -p PREFIX Output file is written into this directory, and file is named according to document title with / replaced with _. This is specifically intended to be used in conjunction with --titledepth for generating docs for Sphix or similar. --doctitle DOCTITLE, -t DOCTITLE Set document title, default is input filename --titledepth TITLEDEPTH, -d TITLEDEPTH Set the document title to it's basename prefixed with titledepth many parent directories (0 for basename only) --notoc, -n Do not include ..contents:: in output --notitle, -e Do not include the document title in output
Please see the examples folder.
While ShellDoc is sufficiently complete to be useful, there are a number of features that could be added to improve it, some that come to mind include:
- Some better syntax to handle the functionality of
- Break out
shelldocinto more modular components. + Add switches to extract individual segments and sections. + Build a library/API other Python code can use to extract individual segments and sections. + Add unit tests for each component.
- Add end-to-end smoke testing.
Contributions in the form of suggestions, bug reports, documentation, and/or source code are gratefully accepted.
See the LICENSE file.