Command Line

qdox

Generate docs/index.html from module contents and metadata

Syntax: qdox [OPTION ...]

Options

-:

run with no options

--debug:

Enable debugging traceback on exceptions

-h|--help|help:

Display this help information

--tomlfile=TOMFILE:

Use TOMFILE instead of "pyproject.toml"

--withcss[=CSSFILE]:

Copy CSSFILE file to the docs folder (default is qdox.css)

Description

The qdox command generates the documentation for a simple Python project. The formatting is designed to use simple text layout as the input so that the same documentation source can be used for both Python help() output and the documentation pages.

The command loads the module specified in the pyproject.toml file and outputs the __doc__ property of the module as the command line documentation. It then outputs the python functions and constants, followed by the project metadata.

You can use your project's pages-build-deployment workflow to deploy the documentation to github.io or to your own custom site by setting the following options in your project Settings-->Pages.

Source: Choose Deploy from a branch
Branch: Choose main and /docs.
Custom domain: Enter one if you have one.

Usage

To use qdox in a project you must do the following:

Install qdox from the repo into the current venv by running the command
```
python3 -m pip install git+https://github.com/dchassin/qdox
```

Run qdox in the project root folder by running the command

qdox -
       If you want to include a CSS file, use the option --withcss=CSSFILE, e.g.,
qdox --withcss=mystyles.css
       The CSSFILE defaults to qdox.css when omitted.

Add/push the new files to GitHub by running the commands
```
git commit -a -m "Add docs"
git push
```

Text Formatting

Text encoding includes the following:

Syntax[COLON] text:

Syntax text

text[COLON]:

Level 2 heading text in module docs or level 3 in function docs

[NEWLINE]:

New paragraph

[4 SPACES]*[SPACE]text:

Bulleted list text

[4 SPACES][DIGIT].[SPACE]text:

Numbered list item

[4 SPACES]label[COLON] text:

Preformatted text

[6 SPACES]text:

List item text continuation

[8 SPACES]text:

Preformatted text

**text**:

Bold text

*text*:

Italic text

!!text!!:

Highlight text

~~text~~:

~~strikeout~~ text

__text__:

underline text

^text:

^superscript word (ends at space)

_text:

_subscript word (ends at space)

[TIC]text[TIC]:

code text

protocol[COLON]//url/:

protocol://url/ formatting with active link

Pro-tips

The module you are documenting must be installed in the active Python environment for qdox to read information about the module.

If you want to output a colon at the end of a paragraph rather than a heading, place a space after the colon and before the end-of-line.

Python Library

Class qdox(Exception)

Error caused by an invalid or missing command line option

Module Functions

`main(argv:list) → int`

Command line interface

Runs the main qdox program. Generates the docs/index.html from the README.md file and from the module created using the pyproject.toml file. If the WITHCSS is set to a file that exists, it also copies that file to the docs/ folder and references it in the HTML file.

Arguments

argv:

argument list (default is sys.argv)

Returns

int:

exit code

Properties

DEBUG (bool):

enable debugging traceback on exception

WITHCSS (str):

enable copying CSS file to docs/

Exceptions

Exception:

exceptions are only raised if DEBUG is True.

FileNotFoundError:

exception raised when an input file is not found.

QdoxError:

exception raised when an invalid command argument is encountered.

Module Variables

E_ERROR = 1

E_OK = 0

E_SYNTAX = 2

Package Metadata

Name	:	qdox
Version	:	0.0.0a5
Description	:	Generate quick documentation for a Python project on GitHub
Authors	:	David P. Chassin
Maintainers	:	David P. Chassin
Requires-Python	:	>= 3.11
Dependencies	:	requests tomli
Keywords	:	github python documentation
License	:	MIT License
Classifiers	:	Development Status :: 3 - Alpha Intended Audience :: Developers License :: OSI Approved :: MIT License Programming Language :: Python :: 3 :: Only Topic :: Software Development :: Libraries
Urls	:	Homepage = https://github.com/eudoxys/qdox Documentation = https://www.eudoxys.com/qdox Repository = https://github.com/eudoxys/qdox.git Issues = https://github.com/eudoxys/qdox/issues
Scripts	:	`qdox` → `main()`