Skip to main content

A Python API compiler for universal Markdown syntax.

Project description

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.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

apimd-1.0.0-cp37.cp38-none-any.whl (8.4 kB view hashes)

Uploaded CPython 3.7 CPython 3.8

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