facile_rs.run_docstring_pipeline

Extract and copy the content of reStructuredText docstrings of Python scripts to a Grav CMS repository.

Description

This script extracts and copies the content of reStructuredText docstrings of Python scripts to a Grav CMS repository.

Contrary to the other pipelines, this script does not copy one file to one page in Grav, but creates a tree of pages below one page (given by the pipeline header). it processes all run.py and __init__.py files.

The PIPELINE and PIPELINE_SOURCE options are used in the same way as in run_markdown_pipeline.py.

In addition, PIPELINE_IMAGES specifies a directory where the images from the docstrings are located and PIPELINE_HEADER and PIPELINE_FOOTER options point to templates which are prepended and appended to each page.

With the PIPELINE_REFS YML file, you can specify replacements for the references in the rst code.

Please refer to https://git.opencarp.org/openCARP/experiments for an example setup.

Usage

usage: run_docstring_pipeline.py [-h] --grav-path GRAV_PATH --pipeline
                                 PIPELINE --pipeline-source PIPELINE_SOURCE
                                 [--pipeline-images PIPELINE_IMAGES]
                                 [--pipeline-header PIPELINE_HEADER]
                                 [--pipeline-footer PIPELINE_FOOTER]
                                 [--pipeline-refs PIPELINE_REFS]
                                 [--output-html]
                                 [--mathjax-location MATHJAX_LOCATION]
                                 [--log-level LOG_LEVEL] [--log-file LOG_FILE]

Named Arguments

--grav-path

Path to the grav repository directory.

--pipeline

Name of the pipeline as specified in the GRAV metadata.

--pipeline-source

Path to the source directory for the pipeline.

--pipeline-images

Path to the images directory for the pipeline.

--pipeline-header

Path to the header template.

--pipeline-footer

Path to the footer template.

--pipeline-refs

Path to the refs yaml file.

--output-html

Output HTML files instead of markdown

Default: False

--mathjax-location

Location of the MathJax script for math rendering in HTML output. This option is only used if –output-html is set. Set to empty string to disable MathJax.

Default: 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'

--log-level

Log level (ERROR, WARN, INFO, or DEBUG)

Default: 'WARN'

--log-file

Path to the log file

Module Contents

Functions

create_parser
main
main_deprecated

Data

logger
FIGURE_PATTERN
REF_PATTERN
METADATA_PATTERN
METADATA_RUN_PATTERN

API

logger = 'getLogger(...)'

FIGURE_PATTERN = '\\.\\. figure\\:\\:\\s(.+?)\\s'

REF_PATTERN = '\\:ref\\:\\`(.+?)\\s\\<(.+?)\\>\\`'

METADATA_PATTERN = "__(.*)__ = [\\']([^\\']*)[\\']"

METADATA_RUN_PATTERN = "EXAMPLE_(.*) = [\\']([^\\']*)[\\']"

create_parser(add_help=True)

main(args)

main_deprecated()