| Name | mosheh JSON |
| Version |
1.3.2
JSON |
| download |
| home_page | None |
| Summary | Mosheh, a tool for creating docs for projects, from Python to Python. |
| upload_time | 2024-12-17 23:44:36 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License Copyright (c) 2024 Lucas Gonçalves da Silva Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
cli
python
documentation
mkdocs
automation
generation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<h1 align="center">
<img src="https://raw.githubusercontent.com/lucasGoncSilva/mosheh/refs/heads/main/.github/logo.svg" height="300" width="300" alt="Logo Mosheh" />
<br>
Mosheh
</h1>
[](https://github.com/LucasGoncSilva/mosheh/blob/main/.github/CHANGELOG.md)
[](https://pypi.org/project/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](https://www.mkdocs.org/) and [Material MkDocs](https://squidfunk.github.io/mkdocs-material/) a documentation respecting the dirs and files hierarchy. The stuff documented for each file are listed below:
- Imports `[ast.Import | ast.ImportFrom]`
- [x] Type `[Native | TrdParty | Local]`
- [x] Path (e.g. 'django.http')
- [x] Code
- Constants `[ast.Assign | ast.AnnAssign]`
- [x] Name (token name)
- [x] Typing Notation (datatype)
- [x] Value (literal or call)
- [x] Code
- Classes `[ast.ClassDef]`
- [ ] Description (docstring)
- [x] Name (class name)
- [x] Parents (inheritance)
- [ ] Methods Defined (nums and names)
- [ ] Example (usage)
- [x] Code
- Funcs `[ast.FunctionDef | ast.AsyncFunctionDef]`
- [ ] Description (docstring)
- [x] Name (func name)
- [x] Type `[Func | Method | Generator | Coroutine]`
- [x] Parameters (name, type, default)
- [x] Return Type (datatype)
- [ ] Raises (exception throw)
- [ ] Example (usage)
- [x] Code
- Assertions `[ast.Assert]`
- [x] Test (assertion by itself)
- [x] Message (opt. message in fail case)
- [x] Code
## Stack
## ToDo List
- [ ] Evaluate use of Rust for better proccessing
- [ ] Evaluate the processing of more files than just Python ones (e.g. `.txt`, `.toml`)
- [x] Migrate dependency system to use [uv](https://docs.astral.sh/uv/)
- [x] Process 25% of Python [AST](https://docs.python.org/3/library/ast.html)'s nodes on `mosheh.handler`
- [x] Process 50% of Python [AST](https://docs.python.org/3/library/ast.html)'s nodes on `mosheh.handler`
- [x] Process 75% of Python [AST](https://docs.python.org/3/library/ast.html)'s nodes on `mosheh.handler`
- [x] Process 100% of Python [AST](https://docs.python.org/3/library/ast.html)'s nodes on `mosheh.handler`
- [ ] Accept structured file (e.g. `mosheh.json`) as parameters replacement
- [ ] Provide an "exclude" config for files/dirs to ignore
- [ ] Insert `tags` for `.md` based on their names/contexts
- [ ] Get and list all metrics of above's statements featured
- [ ] Check for files docstrings and write below filepath
- [ ] Create detail page for classes with docstring and listing class constants and methods
- [ ] Create detail page for functions with docstring and body detail
## 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:
```sh
.
├── 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
│ ├── metadata.py # Metadata about Mosheh itself
│ └── utils.py # Utilities
│
├── tests # Template dir for testing
│ ├── DOC # Doc output dir
│ ├── PROJECT # Template project dir
│ └── unittest # Automated tests
│
├── documentation # Mosheh's documentation dir
│ ├── docs # Dir containing .md files and assets
│ └── mkdocs.yml # MkDocs config file
│
├── pyproject.toml # Mosheh's config file for almost everything
├── uv.lock # uv's lockfile for dealing with dependencies
├── .python-version # Default Python's version to use
│
├── .github # Workflows and social stuff
│
├── LICENSE # Legal stuff, A.K.A donut sue me
│
└── .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:
## Usage
### Local Build and Installation
#### Installing Dependencies
```sh
pip install uv # For installing uv to handle the environment
uv sync # Automatically creates a .venv, activates it and install libs based on uv.lock and pyproject.toml
```
#### Runing Locally
```sh
uv run -m mosheh.main # For running using uv and dealing with Mosheh as a module
```
#### Installing Locally
```sh
uv build # Build pip-like file
uv pip install dist/mosheh-<VERSION>-py3-none-any.whl --force-reinstall # Install Mosheh using generated pip-like file
```
### Testing
```sh
uv run pytest # Run pytest
```
### Parameters
| Call | Type | Mandatory | Default | Example | Description |
| :-------------: | :----: | :--------: | :------------------------------- | :------------------------------ | :--------------------------------------------------------------- |
| `-h`, `--help` | `str` | `Optional` | `None` | `-h`, `--help` | Help message |
| `-root` | `Path` | `Required` | `None` | `-root example/` | Root dir, where the analysis starts. |
| `--repo-name` | `str` | `Optional` | `'GitHub'` | `--repo-name toicin` | Name of the code repository to be mapped. |
| `--repo-url` | `URL` | `Optional` | `'https://github.com/'` | `--repo-url https://random.com` | URL of the code repository to be mapped. |
| `--edit-uri` | `str` | `Optional` | `'blob/main/documentation/docs'` | `--edit-uri blob/main/docs` | URI to view raw or edit blob file. |
| `--logo-path` | `Path` | `Optional` | `None` | `--repo-url .github/logo.svg` | Path for doc/project logo, same Material MkDocs's formats. |
| `--readme-path` | `Path` | `Optional` | `None` | `--repo-url .github/README.md` | Path for `README.md` file to used as homepage. |
| `--verbose` | `int` | `Optional` | `3` - `logging.INFO` | `--verbose 4` | Verbosity level, from 0 (quiet/critical) to 4 (overshare/debug). |
| `--output` | `Path` | `Optional` | `'.'` - current dir | `--output doc/` | Path for documentation output, where to be created. |
## License
This project is under [MIT License](https://choosealicense.com/licenses/mit/). 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "mosheh",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "LucasGonc <lucasgoncsilva04@gmail.com>",
"keywords": "CLI, Python, documentation, MkDocs, automation, generation",
"author": null,
"author_email": "LucasGonc <lucasgoncsilva04@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/16/c6/54f177f57a219739e246af07740dd9eb938842e28045852dc32a98fd9a1d/mosheh-1.3.2.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">\n <img src=\"https://raw.githubusercontent.com/lucasGoncSilva/mosheh/refs/heads/main/.github/logo.svg\" height=\"300\" width=\"300\" alt=\"Logo Mosheh\" />\n <br>\n Mosheh\n</h1>\n\n\n\n\n\n[](https://github.com/LucasGoncSilva/mosheh/blob/main/.github/CHANGELOG.md)\n\n[](https://pypi.org/project/mosheh/)\n\nMosheh, a tool for creating docs for projects, from Python to Python.\n\nBasically, 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](https://www.mkdocs.org/) and [Material MkDocs](https://squidfunk.github.io/mkdocs-material/) a documentation respecting the dirs and files hierarchy. The stuff documented for each file are listed below:\n\n- Imports `[ast.Import | ast.ImportFrom]`\n\n - [x] Type `[Native | TrdParty | Local]`\n - [x] Path (e.g. 'django.http')\n - [x] Code\n\n- Constants `[ast.Assign | ast.AnnAssign]`\n\n - [x] Name (token name)\n - [x] Typing Notation (datatype)\n - [x] Value (literal or call)\n - [x] Code\n\n- Classes `[ast.ClassDef]`\n\n - [ ] Description (docstring)\n - [x] Name (class name)\n - [x] Parents (inheritance)\n - [ ] Methods Defined (nums and names)\n - [ ] Example (usage)\n - [x] Code\n\n- Funcs `[ast.FunctionDef | ast.AsyncFunctionDef]`\n\n - [ ] Description (docstring)\n - [x] Name (func name)\n - [x] Type `[Func | Method | Generator | Coroutine]`\n - [x] Parameters (name, type, default)\n - [x] Return Type (datatype)\n - [ ] Raises (exception throw)\n - [ ] Example (usage)\n - [x] Code\n\n- Assertions `[ast.Assert]`\n\n - [x] Test (assertion by itself)\n - [x] Message (opt. message in fail case)\n - [x] Code\n\n## Stack\n\n\n\n\n\n\n\n\n\n\n\n## ToDo List\n\n- [ ] Evaluate use of Rust for better proccessing\n- [ ] Evaluate the processing of more files than just Python ones (e.g. `.txt`, `.toml`)\n- [x] Migrate dependency system to use [uv](https://docs.astral.sh/uv/)\n- [x] Process 25% of Python [AST](https://docs.python.org/3/library/ast.html)'s nodes on `mosheh.handler`\n- [x] Process 50% of Python [AST](https://docs.python.org/3/library/ast.html)'s nodes on `mosheh.handler`\n- [x] Process 75% of Python [AST](https://docs.python.org/3/library/ast.html)'s nodes on `mosheh.handler`\n- [x] Process 100% of Python [AST](https://docs.python.org/3/library/ast.html)'s nodes on `mosheh.handler`\n- [ ] Accept structured file (e.g. `mosheh.json`) as parameters replacement\n- [ ] Provide an \"exclude\" config for files/dirs to ignore\n- [ ] Insert `tags` for `.md` based on their names/contexts\n- [ ] Get and list all metrics of above's statements featured\n- [ ] Check for files docstrings and write below filepath\n- [ ] Create detail page for classes with docstring and listing class constants and methods\n- [ ] Create detail page for functions with docstring and body detail\n\n## Arch\n\nMosheh'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.\n\nHere 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:\n\n```sh\n.\n\u251c\u2500\u2500 mosheh # Mosheh's source-code\n\u2502 \u251c\u2500\u2500 codebase.py # Codebase reading logic\n\u2502 \u251c\u2500\u2500 constants.py # Constants to be evaluated\n\u2502 \u251c\u2500\u2500 custom_types.py # Custom data types\n\u2502 \u251c\u2500\u2500 doc.py # Documentation build logic\n\u2502 \u251c\u2500\u2500 handlers.py # Codebase nodes handlers functions\n\u2502 \u251c\u2500\u2500 main.py # Entrypoint\n\u2502 \u251c\u2500\u2500 metadata.py # Metadata about Mosheh itself\n\u2502 \u2514\u2500\u2500 utils.py # Utilities\n\u2502\n\u251c\u2500\u2500 tests # Template dir for testing\n\u2502 \u251c\u2500\u2500 DOC # Doc output dir\n\u2502 \u251c\u2500\u2500 PROJECT # Template project dir\n\u2502 \u2514\u2500\u2500 unittest # Automated tests\n\u2502\n\u251c\u2500\u2500 documentation # Mosheh's documentation dir\n\u2502 \u251c\u2500\u2500 docs # Dir containing .md files and assets\n\u2502 \u2514\u2500\u2500 mkdocs.yml # MkDocs config file\n\u2502\n\u251c\u2500\u2500 pyproject.toml # Mosheh's config file for almost everything\n\u251c\u2500\u2500 uv.lock # uv's lockfile for dealing with dependencies\n\u251c\u2500\u2500 .python-version # Default Python's version to use\n\u2502\n\u251c\u2500\u2500 .github # Workflows and social stuff\n\u2502\n\u251c\u2500\u2500 LICENSE # Legal stuff, A.K.A donut sue me\n\u2502\n\u2514\u2500\u2500 .gitignore # Git \"exclude\" file\n```\n\nIt 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:\n\n\n\n## Usage\n\n### Local Build and Installation\n\n#### Installing Dependencies\n\n```sh\npip install uv # For installing uv to handle the environment\n\nuv sync # Automatically creates a .venv, activates it and install libs based on uv.lock and pyproject.toml\n```\n\n#### Runing Locally\n\n```sh\nuv run -m mosheh.main # For running using uv and dealing with Mosheh as a module\n```\n\n#### Installing Locally\n\n```sh\nuv build # Build pip-like file\n\nuv pip install dist/mosheh-<VERSION>-py3-none-any.whl --force-reinstall # Install Mosheh using generated pip-like file\n```\n\n### Testing\n\n```sh\nuv run pytest # Run pytest\n```\n\n### Parameters\n\n| Call | Type | Mandatory | Default | Example | Description |\n| :-------------: | :----: | :--------: | :------------------------------- | :------------------------------ | :--------------------------------------------------------------- |\n| `-h`, `--help` | `str` | `Optional` | `None` | `-h`, `--help` | Help message |\n| `-root` | `Path` | `Required` | `None` | `-root example/` | Root dir, where the analysis starts. |\n| `--repo-name` | `str` | `Optional` | `'GitHub'` | `--repo-name toicin` | Name of the code repository to be mapped. |\n| `--repo-url` | `URL` | `Optional` | `'https://github.com/'` | `--repo-url https://random.com` | URL of the code repository to be mapped. |\n| `--edit-uri` | `str` | `Optional` | `'blob/main/documentation/docs'` | `--edit-uri blob/main/docs` | URI to view raw or edit blob file. |\n| `--logo-path` | `Path` | `Optional` | `None` | `--repo-url .github/logo.svg` | Path for doc/project logo, same Material MkDocs's formats. |\n| `--readme-path` | `Path` | `Optional` | `None` | `--repo-url .github/README.md` | Path for `README.md` file to used as homepage. |\n| `--verbose` | `int` | `Optional` | `3` - `logging.INFO` | `--verbose 4` | Verbosity level, from 0 (quiet/critical) to 4 (overshare/debug). |\n| `--output` | `Path` | `Optional` | `'.'` - current dir | `--output doc/` | Path for documentation output, where to be created. |\n\n## License\n\nThis project is under [MIT License](https://choosealicense.com/licenses/mit/). 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.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Lucas Gon\u00e7alves da Silva Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Mosheh, a tool for creating docs for projects, from Python to Python.",
"version": "1.3.2",
"project_urls": {
"Changelog": "https://github.com/LucasGoncSilva/mosheh/blob/main/.github/CHANGELOG.md",
"Documentation": "https://lucasgoncsilva.github.io/mosheh/",
"Issues": "https://github.com/LucasGoncSilva/mosheh/issues",
"Repository": "https://github.com/lucasGoncSilva/mosheh/"
},
"split_keywords": [
"cli",
" python",
" documentation",
" mkdocs",
" automation",
" generation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8c4a18446de1f2e3400ba1cb8205031c256e311a4bf7407da231630b6487eb4d",
"md5": "9489eb7e8ba9a452726e50ecd919c77a",
"sha256": "2ce8f64f3824c6a881a7c05780028f7b6926b45c0dbb876109a60c2565c2f42f"
},
"downloads": -1,
"filename": "mosheh-1.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9489eb7e8ba9a452726e50ecd919c77a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 33618,
"upload_time": "2024-12-17T23:44:35",
"upload_time_iso_8601": "2024-12-17T23:44:35.916301Z",
"url": "https://files.pythonhosted.org/packages/8c/4a/18446de1f2e3400ba1cb8205031c256e311a4bf7407da231630b6487eb4d/mosheh-1.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "16c654f177f57a219739e246af07740dd9eb938842e28045852dc32a98fd9a1d",
"md5": "c0a4b853b15ec1f38f0db794d14efdde",
"sha256": "40a18769ca3d138091c5c815a58f6c2e7cc3d50a9e49e005601ece31c50ec064"
},
"downloads": -1,
"filename": "mosheh-1.3.2.tar.gz",
"has_sig": false,
"md5_digest": "c0a4b853b15ec1f38f0db794d14efdde",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 34502,
"upload_time": "2024-12-17T23:44:36",
"upload_time_iso_8601": "2024-12-17T23:44:36.886018Z",
"url": "https://files.pythonhosted.org/packages/16/c6/54f177f57a219739e246af07740dd9eb938842e28045852dc32a98fd9a1d/mosheh-1.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-17 23:44:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LucasGoncSilva",
"github_project": "mosheh",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mosheh"
}
