Getting Started

The pyp2qmd package provides (i) a console tool to set up a skeleton of the documentation, but also (ii) allows to write a small Python script to do so. The latter allows for somewhat more control (tough limited at the moment).

Documentation skeleton via console

The package is shipped with an executable called pyp2qmd, providing a series of options to set up the basic structure (sekelton) of a Python package quarto documentation.

It will load an existing package and extract all exported functions and classes (from the main module), creating quarto markdown manuals for each of them. Alongside the manuals a basic [quarto][quarto] website structure is set up.

Usage

The pyp2qmd executable provides a series of arguments whereof two are mandatory, namely action and -p/--package. For details, see pyp2qmd --help (included in the tab ‘Show usage help’).

• action: One of init (initialize documentation skeleton) or document (update documentation).
• -p/--package: Name of the package to be documented.

Thus, in the simplest case the command looks as follows:

#| eval: false
pyp2qmd init --package <name_of_package>

All other arguments have defaults (see --help) which can be adjusted if needed.

Show usage help

pyp2qmd --help

usage: pyp2qmd [-h] [-p PACKAGE] [--overwrite] [--quarto_dir QUARTO_DIR]
               [--man_dir MAN_DIR] [--output_dir OUTPUT_DIR]
               [--docstringstyle DOCSTRINGSTYLE] [--include_hidden]
               [--examples_dir EXAMPLES_DIR] [--silent]
               action

positional arguments:
  action                Action to perform, one of: init, document, examples

options:
  -h, --help            show this help message and exit
  -p PACKAGE, --package PACKAGE
                        Name of the python package.
  --overwrite           Only used if action = create; will overwrite
                        _quarto.yml if needed.
  --quarto_dir QUARTO_DIR
                        Name of the target directory for rendered quarto
                        website. Defaults to "_quarto".
  --man_dir MAN_DIR     Folder to store the function/class manual qmds
                        (subfolder of quarto_dir). Defaults to "man".
  --output_dir OUTPUT_DIR
                        Name of the target directory for rendered quarto
                        website,relative to quarto_dir. Defaults to "_site".
  --docstringstyle DOCSTRINGSTYLE
                        Docstring type (format). Defaults to "GOOGLE".
  --include_hidden      If set, hidden functions and methods will also be
                        documented (functions/methods starting with _ or __).
  --examples_dir EXAMPLES_DIR
                        Name of the target directory for docstring examples
                        (qmds). Only used if action is 'examples', defaults to
                        "_examples".
  --silent              If set, output will be suppressed.

File structure created

This will create the following structure (for --package pyp2qmd):

pyp2qmd.Config Object:
    Action:            init
    Package:           pyp2qmd
    Quarto dir:        /tmp/tmp8zf2i9i3
    Man page dir:      man
    Output dir:        _site
    Overwrite:         False
    Examples dir:      _examples
    Include hidden:    False
    Docstring style:   GOOGLE

_quarto
├── _quarto.yml
├── index.qmd
├── man
│   ├── pyp2qmd.Config.Config.get.qmd
│   ├── pyp2qmd.Config.Config.is_set_up.qmd
│   ├── pyp2qmd.Config.Config.qmd
│   ├── pyp2qmd.Config.Config.setup.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.add_favicon.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.add_issue_url.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.add_logo.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.add_navbar_menu.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.add_navbar_page.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.add_navbar_right.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.add_repo_url.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.add_scss.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.config_get.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.document.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.document_classes.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.document_functions.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.examples.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.examples_classes.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.examples_functions.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.get_classes.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.get_functions.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.qmd
│   ├── pyp2qmd.DocConverter.DocConverter.update_quarto_yml.qmd
│   ├── pyp2qmd.ManPage.ManPage.config_get.qmd
│   ├── pyp2qmd.ManPage.ManPage.fullname.qmd
│   ├── pyp2qmd.ManPage.ManPage.get.qmd
│   ├── pyp2qmd.ManPage.ManPage.get_example_qmd.qmd
│   ├── pyp2qmd.ManPage.ManPage.getmembers.qmd
│   ├── pyp2qmd.ManPage.ManPage.isclass.qmd
│   ├── pyp2qmd.ManPage.ManPage.isfunction.qmd
│   ├── pyp2qmd.ManPage.ManPage.qmd
│   ├── pyp2qmd.ManPage.ManPage.quartofile.qmd
│   ├── pyp2qmd.ManPage.ManPage.signature.qmd
│   ├── pyp2qmd.ManPage.ManPage.write_examples_qmd.qmd
│   ├── pyp2qmd.ManPage.ManPage.write_qmd.qmd
│   ├── pyp2qmd.demofunctions.demofun_allfine.qmd
│   ├── pyp2qmd.demofunctions.demofun_wrong.qmd
│   └── pyp2qmd.demofunctions.demofun_wrong2.qmd
└── pyp.scss

1 directory, 41 files

The file _quarto.yml contains the template for the quarto website skeleton, index.qmd a template of the websites entry page (home). In addition, pyp.scss with a series of style adjustments.

In addition, a folder is created containing the man pages (default --man_dir name is "man") for all exported functions and classes as well as their methods. To render the website simply execute:

(cd _quarto && quarto render)

This will render the website and output a series of static HTML files into the output_folder (_quarto/_site by default).

Documentation via script

Alternatively, a small custom Python script can be written to create the documentation. This allows to add additional pages to the quarto website top navigation.

The script below is creating the documentation you are reading currently.

#!/usr/bin/env python

def main():
    from os.path import join, basename
    from pyp2qmd import Config, DocConverter

    # Initialize Config; parses user arguments via argparse
    config  = Config()
    config.setup(action = "init", package = "pyp2qmd", overwrite = True)

    # Initialize DocConverter; creates _quarto.yml,
    # pyp.sass, and index.qmd if needed.
    docconv = DocConverter(config)

    docconv.document()
    docconv.update_quarto_yml()

    # Adding test page
    src = join("make_docs", "getting_started.qmd")
    docconv.add_navbar_page(src, basename(src), "Getting started")
    src = join("make_docs", "designg_philosphy.qmd")
    docconv.add_navbar_page(src, basename(src), "Design philosophy")

if __name__ == "__main__":
    main()