mosheh 1.0.0

Mosheh, a tool for creating docs for projects, from Python to Python.

Mosheh

Mosheh, a tool for creating docs for projects, from Python to Python.

Basically, Mosheh lists all files you points to, saves every single notorious statement of definition on each file iterated, all using Python ast native module for handling the AST and then generating with MkDocs and Material MkDocs a documentation respecting the dirs and files hierarchy. The stuff documented for each file are listed below:

• Imports [ast.Import | ast.ImportFrom]

  • Type [Native | TrdParty | Local]
  • Path (e.g. 'django.http')
  • Code

• Constants [ast.Assign | ast.AnnAssign]

  • Name (token name)
  • Typing Notation (datatype)
  • Value (literal or call)
  • Code

• Classes [ast.ClassDef]

  • Description (docstring)
  • Name (class name)
  • Parents (inheritance)
  • Methods Defined (nums and names)
  • Example (usage)
  • Code

• Funcs [ast.FunctionDef | ast.AsyncFunctionDef]

  • Description (docstring)
  • Name (func name)
  • Type [Func | Method | Generator | Coroutine]
  • Parameters (name, type, default)
  • Return Type (datatype)
  • Raises (exception throw)
  • Example (usage)
  • Code

• Assertions [ast.Assert]

  • Test (assertion by itself)
  • Message (opt. message in fail case)
  • Code

Stack

Arch

Mosheh's architecture can be interpreted in two ways: the directory structure and the interaction of the elements that make it up. A considerable part of a project is - or at least should be - that elements that are dispensable for its functionality are in fact dispensable, such as the existence of automated tests; they are important so that any existing quality process is kept to a minimum acceptable level, but if all the tests are deleted, the tool still works.

Here it is no different, a considerable part of Mosheh is, in fact, completely dispensable; follow below the structure of directories and relevant files that are part of this project:

.
├── mosheh                      # Mosheh's source-code
│   ├── codebase.py             # Codebase reading logic
│   ├── constants.py            # Constants to be evaluated
│   ├── custom_types.py         # Custom data types
│   ├── doc.py                  # Documentation build logic
│   ├── handlers.py             # Codebase nodes handlers functions
│   ├── main.py                 # Entrypoint
│   └── utils.py                # Utilities
│
├── tests                       # Template dir for testing
│   ├── DOC                     # Doc output dir
│   └── PROJECT                 # Template project dir
│
├── requirements.txt            # Mosheh's dependencies
│
├── .github                     # Workflows and social stuff
│
├── LICENSE                     # Legal stuf, A.K.A donut sue me
│
├── ruff.toml                   # Ruff config file
│
└── .gitignore                  # Git "exclude" file

It is to be expected that if the tests/ directory is deleted, Mosheh itself will not be altered in any way, so much so that when a tool is downloaded via pip or similar, the tool is not accompanied by tests, licenses, development configuration files or workflows. So, to help you understand how the mosheh/ directory works, here's how the functional elements interact with each other:

flowchart LR

subgraph YOUR_ENV
  gen_doc[/"Generated Doc"/]:::Other
  base[/"Project"/]:::Other
end

subgraph MOSHEH
  main("main.py"):::Mosheh
  codebase("codebase.py"):::Mosheh
  handlers("handlers.py"):::Mosheh
  types{{"custom_types.py"}}:::Mosheh
  utils{{"utils.py"}}:::Mosheh
  const("constants.py"):::Mosheh
  doc("doc.py"):::Mosheh
end


const -..-> doc
types -.-> main & codebase & utils & handlers & doc
handlers -.-> codebase
utils -.-> codebase & doc & handlers

base --> main
main --> codebase
codebase --> doc
doc --> gen_doc


style YOUR_ENV fill:#057,color:#ffde57,stroke:#ffde57;
style MOSHEH fill:#1a1a1a,color:#fff,stroke:#808080;

classDef Other fill:#ffde57,color:#057,stroke:#057;
classDef Mosheh fill:#404040,color:#fff,stroke:#ccc;

linkStyle default stroke:#808080
linkStyle 10,11,12,13 stroke:#fff

Usage

Local Build and Installation

pip install -r requirements.txt  # Install all dependencies in your local environment

# or

pip install wheel setuptools  # Install only build dependencies in your local environment

python3 setup.py sdist bdist_wheel  # Build pip-like file

pip install dist/mosheh-<VERSION>-py3-none-any.whl --force-reinstall  # Install Mosheh using generated pip-like file

Running

mosheh [-h] -root ROOT [--repo-name REPO_NAME] [--repo-url REPO_URL] [--logo-path LOGO_PATH] [--readme-path README_PATH] [--exit EXIT]

Parameters

Call	Type	Mandatory	Default	Example	Action
-h, --help	str	Optional	None	-h, --help	Help message
-root	str	Required	None	-root example/	Root to start looking for
--repo-name	str	Optional	'GitHub'	--repo-name toicin	Repo name
--repo-url	str	Optional	'https://github.com/'	--repo-url https://random.com	Repo URL
--logo-path	str	Optional	''	--repo-url .github/logo.svg	Path to project logo
--readme-path	str	Optional	''	--repo-url .github/README.md	Path to project README.md file
--exit	str	Optional	'.'	--exit doc/	Doc output path

License

This project is under MIT License. A short and simple permissive license with conditions only requiring preservation of copyright and license notices. Licensed works, modifications, and larger works may be distributed under different terms and without source code.