Skip to main content

Minimal python API documentation generation for https://mathy.ai

Project description

mathy_pydoc

IMPORTANT This is a fork of the pydoc_markdown repo to use the legacy version for Mathy's simple API doc needs. See the official repo for the latest stable updates: https://github.com/NiklasRosenstein/pydoc-markdown

insipired by the [Keras] Documentation

Installation

pip install mathy_pydoc

Usage

mathy_pydoc generates plain Markdown files from Python modules using the mathy_pydoc command. Specify one or more module names on the command-line. Supports the + syntax to include members of the module (or ++ to include members of the members, etc.)

mathy_pydoc mypackage+ mypackage.mymodule+ > docs.md

Syntax

Cross-references

Symbols in the same namespace may be referenced by using a hash-symbol (#) directly followed by the symbols' name, including relative references. Note that using parentheses for function names is encouraged and will be ignored and automatically added when converting docstrings. Examples: #ClassName.member or #mod.function().

For absolute references for modules or members in names that are not available in the current global namespace, #::mod.member must be used (note the two preceeding two double-colons).

For long reference names where only some part of the name should be displayed, the syntax #X~some.reference.name can be used, where X is the number of elements to keep. If X is omitted, it will be assumed 1. Example: #~some.reference.name results in only name being displayed.

In order to append additional characters that are not included in the actual reference name, another hash-symbol can be used, like #Signal#s.

Sections

Sections can be generated with the Markdown # <Title> syntax. It is important to add a whitespace after the hash-symbol (#), as otherwise it would represent a cross-reference. Some special sections alter the rendered result of their content, including

  • Arguments (1)
  • Parameters (1)
  • Attributes (1)
  • Members (1)
  • Raises (2)
  • Returns (2)

(1): Lines beginning with <ident> [(<type>[, ...])]: are treated as argument/parameter or attribute/member declarations. Types listed inside the parenthesis (optional) are cross-linked, if possible. For attribute/member declarations, the identifier is typed in a monospace font.

(2): Lines beginning with <type>[, ...]: are treated as raise/return type declarations and the type names are cross-linked, if possible.

Lines following a name's description are considered part of the most recent documentation unless separated by another declaration or an empty line. <type> placeholders can also be tuples in the form (<type>[, ...]).

Code Blocks

GitHub-style Markdown code-blocks with language annotations can be used.

```python
>>> for i in range(100):
...
```

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mathy_pydoc-0.7.3.tar.gz (11.3 kB view hashes)

Uploaded Source

Built Distribution

mathy_pydoc-0.7.3-py3-none-any.whl (17.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page