Skip to main content

A Python API compiler for universal Markdown syntax.

Project description

Build status PyPI

apimd

A Python API compiler for universal Markdown syntax.

Required Python 3.7 and above.

Install

Install by pip:

pip install apimd

From Git repository:

python setup.py install

Run directly:

python launcher.py --help

Command

Following syntax are allowed:

apimd module_name
apimd Module-Name=module_name
apimd "Module Name=module_name"

The first is the readable name of the package; the second is the name used in import syntax. Please make sure you can import the package by the given name in current path.

The output path can be choose by "-d" and "--dir" option, default is docs. Multiple modules are supported either.

apimd module1 module2 -d out_path

If you just want to test, use dry run.

apimd module --dry

Rules

Basically, this compiler can extract docstrings from those "public" objects:

  • Modules
  • Functions
  • Generators
  • Classes and its methods

According to PEP 8, "public" means a name can't starts with underscore symbol "_". And the magic methods are not "public" too, apart from __init__ method. (Naming Conventions)

Builtins object (int, str, list, dict, etc.) has no docstring their owned. So even they are public name style or listed in __all__, this compiler will still skip them (like __version__ or MY_GLOBAL). Please pack them into functions or classes such as Enum, or mention them in the docstring of root module.

In module wise, a package force required a list object __all__ to show all of global names to prevent external imported names and from m import * syntax. (Global Variable Names)

This compiler can detect properties, class attributes, static methods and abstract methods as well. Object attributes should be noted in the stub files or use Variable Annotations (PEP 526).

Stubs

If a module has a stub file, the stub file will be loaded instead of the module. So docstring should be written in stub file first.

Inner links

The docstring can refer the names in the same module or same class. Use [name], [class.attribute] or [attribute] syntax to refer them. But if attribute name is conflict with global name, the global name will preferred.

Project details


Download files

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

Files for apimd, version 1.0.1
Filename, size File type Python version Upload date Hashes
Filename, size apimd-1.0.1-cp37.cp38-none-any.whl (8.6 kB) File type Wheel Python version cp37.cp38 Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page