handsdown-fork 0.1.0__tar.gz

handsdown_fork-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) FredHappyface
+Copyright (c) 2019 Vlad Emelianov
+
+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.

handsdown_fork-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include handsdown/templates/**/*.jinja2
+include py.typed
+include README.md
+include LICENSE

handsdown_fork-0.1.0/PKG-INFO

@@ -0,0 +1,436 @@
+Metadata-Version: 2.4
+Name: handsdown-fork
+Version: 0.1.0
+Summary: A fork of handsdown, the python docstring-based documentation generator for lazy perfectionists.
+Author: FredHappyface
+License: MIT License
+        
+        Copyright (c) FredHappyface
+        Copyright (c) 2019 Vlad Emelianov
+        
+        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.
+        
+Project-URL: Homepage, https://vemel.github.io/handsdown
+Project-URL: Documentation, https://vemel.github.io/handsdown
+Project-URL: Repository, https://github.com/vemel/handsdown
+Project-URL: Changelog, https://github.com/vemel/handsdown/releases
+Project-URL: Issues, https://github.com/vemel/handsdown/issues
+Keywords: autodoc,documentation,generator,markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Framework :: Django
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Typing :: Typed
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: importlib-resources
+Requires-Dist: jinja2
+Requires-Dist: black
+Requires-Dist: basedpyright>=1.39.8
+Requires-Dist: typing-extensions>=4.12.2
+Dynamic: license-file
+
+# 🙌 Handsdown-fork
+
+[![GitHub top language](https://img.shields.io/github/languages/top/FHPythonUtils/handsdown-fork.svg?style=for-the-badge&cacheSeconds=28800)](../../)
+[![Issues](https://img.shields.io/github/issues/FHPythonUtils/handsdown-fork.svg?style=for-the-badge&cacheSeconds=28800)](../../issues)
+[![License](https://img.shields.io/github/license/FHPythonUtils/handsdown-fork.svg?style=for-the-badge&cacheSeconds=28800)](/LICENSE.md)
+[![Commit activity](https://img.shields.io/github/commit-activity/m/FHPythonUtils/handsdown-fork.svg?style=for-the-badge&cacheSeconds=28800)](../../commits/master)
+[![Last commit](https://img.shields.io/github/last-commit/FHPythonUtils/handsdown-fork.svg?style=for-the-badge&cacheSeconds=28800)](../../commits/master)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/handsdown-fork.svg?style=for-the-badge&cacheSeconds=28800)](https://pypistats.org/packages/handsdown-fork)
+[![PyPI Total Downloads](https://img.shields.io/badge/dynamic/json?style=for-the-badge&label=total%20downloads&query=%24.total_downloads&url=https%3A%2F%2Fapi%2Epepy%2Etech%2Fapi%2Fv2%2Fprojects%2Fattestationcheck)](https://pepy.tech/project/handsdown-fork)
+[![PyPI Version](https://img.shields.io/pypi/v/handsdown-fork.svg?style=for-the-badge&cacheSeconds=28800)](https://pypi.org/project/handsdown-fork)
+
+A fork of handsdown, the python docstring-based documentation generator for lazy perfectionists.
+
+Huge thanks to <https://github.com/vemel/handsdown> for all of the groundwork!
+
+- [🙌 Handsdown-fork](#-handsdown-fork)
+  - [Features](#features)
+  - [Do you need handsdown-fork?](#do-you-need-handsdown-fork)
+  - [Examples](#examples)
+  - [Usage](#usage)
+    - [💻 From command line](#-from-command-line)
+    - [🚀 Use a new Material design](#-use-a-new-material-design)
+    - [📝 As a GitHub Pages manager](#-as-a-github-pages-manager)
+    - [🐏 Deploy on Read the Docs](#-deploy-on-read-the-docs)
+    - [📋 Build static HTML](#-build-static-html)
+    - [🧩 As a module](#-as-a-module)
+    - [⌨️ CLI arguments](#️-cli-arguments)
+  - [Project Documentation](#project-documentation)
+  - [Installation](#installation)
+  - [Language information](#language-information)
+  - [Working with the repo](#working-with-the-repo)
+  - [Community Files](#community-files)
+    - [Licence](#licence)
+    - [Code of Conduct](#code-of-conduct)
+    - [Contributing](#contributing)
+    - [Security](#security)
+    - [Support](#support)
+
+## Features
+
+- [Material design](#-use-a-new-material-design) support!
+- [PEP 257](https://www.python.org/dev/peps/pep-0257/),
+  [Google](http://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings),
+  [Sphinx](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html)
+  and [reStructuredText](https://www.python.org/dev/peps/pep-0287/)
+  docstrings support. All of them are converted to a valid Markdown.
+- Works with [Django](https://www.djangoproject.com/) and [Flask](https://palletsprojects.com/p/flask/) apps
+- Can be used locally, or
+  [right on GitHub](https://github.com/FHPythonUtils/handsdown-fork/blob/docs/README.md) or even deployed on
+  [GitHub Pages](https://vemel.github.io/handsdown/) and [Read the Docs](https://handsdown.readthedocs.io/)!
+- Signatures for every class, function, property and method.
+- Support for type annotations. Even for the ones from the `__future__`!
+- Nice list of all modules in [Index](https://github.com/FHPythonUtils/handsdown-fork/blob/docs/README.md)
+- Gather all scattered `README.md` in submodules to one place
+- Find related source code from every doc section.
+- Make links by just adding `module.import.String` to docs.
+- Do you use type annotations? Well, you get auto-discovery of related modules for free!
+
+## Do you need handsdown-fork?
+
+You definitely *do* if you:
+
+- prefer to automate documentation builds
+- work with a team and plan to simplify knowledge sharing
+- want to show your project without navigating through a source code
+- build `Django` or `Flask` applications
+- are proud of your project and not afraid to show it
+- love Open Source
+
+## Examples
+
+- [All documentation](https://vemel.github.io/handsdown/) in this project
+- [Main](https://github.com/FHPythonUtils/handsdown-fork/blob/main/examples/main_example.py) with [generated output](https://github.com/FHPythonUtils/handsdown-fork/tree/docs/examples/main_example.md)
+- [RST docstrings](https://github.com/FHPythonUtils/handsdown-fork/blob/main/examples/rst_docstrings.py) with [generated output](https://github.com/FHPythonUtils/handsdown-fork/tree/docs/examples/rst_docstrings.md)
+- [Google docstrings](https://github.com/FHPythonUtils/handsdown-fork/blob/main/examples/google_docstrings.py) with [generated output](https://github.com/FHPythonUtils/handsdown-fork/tree/docs/examples/google_docstrings.md)
+- [PEP 257 docstrings](https://github.com/FHPythonUtils/handsdown-fork/blob/main/examples/pep257_docstrings.py) with [generated output](https://github.com/FHPythonUtils/handsdown-fork/tree/docs/examples/pep257_docstrings.md)
+- [Sphinx docstrings](https://github.com/FHPythonUtils/handsdown-fork/blob/main/examples/sphinx_docstrings.py) with [generated output](https://github.com/FHPythonUtils/handsdown-fork/tree/docs/examples/sphinx_docstrings.md)
+- [Type annotations](https://github.com/FHPythonUtils/handsdown-fork/blob/main/examples/typed.py) with [generated output](https://github.com/FHPythonUtils/handsdown-fork/tree/docs/examples/typed.md)
+- [Comment-style type annotations](https://github.com/FHPythonUtils/handsdown-fork/blob/main/examples/comment_typed.py) with [generated output](https://github.com/FHPythonUtils/handsdown-fork/tree/docs/examples/comment_typed.md)
+
+## Usage
+
+### 💻 From command line
+
+Just go to your favorite project that has lots of docstrings but missing
+auto-generated docs and let `handsdown` do the thing.
+
+```bash
+cd ~/my/project
+
+# build documentation *.md* files in docs/* directory
+handsdown
+
+# or provide custom output directory: output_dir/*
+handsdown -o output_dir
+
+# generate docs only for my_module, but exclude migrations
+handsdown my_module --exclude my_module/migrations
+
+# generate documentation for deployment
+handsdown --external `git config --get remote.origin.url` -n ProjectName --branch main --create-configs
+```
+
+Navigate to `docs/README.md` to check your new documentation!
+
+### 🚀 Use a new Material design
+
+- Add `mkdocs` and `mkdocs-material` to your dev dependencies or just install them
+
+```bash
+# generate MarkDown documentation in docsmd folder
+handsdown --external `git config --get remote.origin.url` -o docsmd -n <project_name> --theme=material --create-configs
+
+# generate html files to docs folder
+python -m mkdocs build
+```
+<!-- 
+### 📦 As a Docker image
+
+Work in progress  -->
+
+### 📝 As a GitHub Pages manager
+
+With `--external` CLI flag, `handsdown` generates all required configuration
+for [GitHub Pages](https://pages.github.com/), so you just need to setup your
+GitHub repository.
+
+```bash
+# Generate documentation that points to main branch
+# do not use custom output location, as `GitHub Pages`
+# works only with `docs` directory
+handsdown --external `git config --get remote.origin.url` --create-configs
+
+# or specify GitHub url directly
+handsdown --external https://github.com/<user>/<project> --create-configs
+```
+
+- Generate documentation with `--external` flag as shown above, do not use `--output`
+  flag, only `docs` folder is supported by `GitHub Pages`
+- Commit and push all changes a to `main` branch.
+- Set your GitHub project `Settings` > `GitHub Pages` > `Source` to `main branch /docs folder`
+
+All set! You can change `docs/_config.yml` to add your own touch.
+
+With `--external` flag links to your source are absolute and point to your GitHub repo. If you
+still want to have relative links to source, e.g. for using docs locally,
+generate docs to another folder
+
+```bash
+# `docs_local` folder will be created in your project root
+# you probably want to add it to .gitignore
+handsdown -o docs_local
+```
+
+### 🐏 Deploy on Read the Docs
+
+With `--external` CLI flag, `handsdown` generates all required configuration
+for [Read the Docs](https://readthedocs.org/), so you just need to to add your
+GitHub repository to `Read the Docs`.
+
+```bash
+# Generate documentation that points to main branch
+# do not use custom output location, as `GitHub Pages`
+# works only with `docs` directory
+handsdown --external `git config --get remote.origin.url` --create-configs
+
+# or specify GitHub url directly
+handsdown --external https://github.com/<user>/<project>/ --create-configs
+```
+
+- Generate documentation with `--external` flag as shown above, do not use `--output`
+  flag, only `docs` folder is supported by `Read the Docs`
+- Commit and push all changes a to `main` branch.
+- Add your repository on [Read the Docs](https://readthedocs.org/)
+
+All set! You can change `.readthedocs.yml` and `mkdocs.yml` to add your own touch.
+
+### 📋 Build static HTML
+
+```bash
+# Generate documentation that points to main branch
+# with source links pointing to your repository
+# this command also creates `mkdocs.yml`
+handsdown --external `git config --get remote.origin.url` --create-configs
+
+# Run mkdocs to build HTML
+python -m mkdocs build
+```
+
+### 🧩 As a module
+
+```python
+from handsdown.generator import Generator
+from handsdown.utils.path_finder import PathFinder
+
+# this is our project root directory
+repo_path = Path.cwd()
+
+# this little tool works like `pathlib.Path.glob` with some extra magic
+# but in this case `repo_path.glob("**/*.py")` would do as well
+path_finder = PathFinder(repo_path, "**/*.py")
+
+# no docs for tests and build
+path_finder.exclude("tests/*", "build/*")
+
+# initialize generator
+handsdown = Generator(
+    input_path=repo_path,
+    output_path=repo_path / 'output',
+    source_paths=path_finder.glob("**/*.py")
+)
+
+# generate all docs at once
+handsdown.generate_docs()
+
+# or generate just for one doc
+handsdown.generate_doc(repo_path / 'my_module' / 'source.py')
+
+# generate index.md file
+handsdown.generate_index()
+
+# and generate GitHub Pages and Read the Docs config files
+handsdown.generate_configs()
+
+# navigate to `output` dir and check results
+```
+
+### ⌨️ CLI arguments
+
+```bash
+handsdown [-h] [--exclude [EXCLUDE ...]] [-i INPUT_PATH] [-f [FILES ...]]
+  [-o OUTPUT_PATH] [--external REPO_URL] [--source-code-path REPO_PATH]
+  [--branch BRANCH] [--toc-depth TOC_DEPTH] [--cleanup] [-n PROJECT_NAME]
+  [-e ENCODING] [--panic] [-d] [-q] [-V]
+  [include ...]
+```
+
+| Argument | Description | Default |
+|-|-|-|
+| `include` | Path expressions to include source files | |
+| `--exclude` | Path expressions to exclude source files | `'build/*' 'tests/*' 'test/*' '*/__pycache__/*' '.*/*'` |
+| `-i` / `--input-path` | Path to project root folder | `<cwd>` |
+| `-f` / `--files` | List of source files to use for generation. If empty - all are used. | |
+| `-o` / `--output-path` | Path to output folder | `<cwd>/docs` |
+| `--external` | Build docs and config for external hosting, GitHub Pages or Read the Docs. Provide the project GitHub .../blob/main/ URL here. | |
+| `--source-code-path` | Path to source code in the project. Overrides `--branch` CLI argument | |
+| `--branch` | Main branch name | `main` |
+| `--toc-depth` | Maximum depth of child modules ToC | `3` |
+| `--cleanup` | Remove orphaned auto-generated docs | |
+| `-n` / `--name` | Project name | `<cwd>.name` |
+| `-e` / `--encoding` | Input and output file encoding | `utf-8` |
+| `--panic` | Panic and die on import error | |
+| `--debug` | Show debug messages| |
+| `--quiet` | Hide log output | |
+| `--create-configs` | Create config files for deployment to RtD and GitHub Pages | |
+| `-t` / `--theme` | Output mkdocs theme: `readthedocs` or `material` | `readthedocs` |
+| `-h` | Show help | |
+
+## Project Documentation
+
+A high-level overview of how the documentation is organized organized will help you know
+where to look for certain things:
+
+<!--
+- [Tutorials](/documentation/tutorials) take you by the hand through a series of steps to get
+  started using the software. Start here if you’re new.
+-->
+- The [Technical Reference](/docs) documents APIs and other aspects of the
+  machinery. This documentation describes how to use the classes and functions at a lower level
+  and assume that you have a good high-level understanding of the software. Note this is generated
+  with handsdown-fork
+<!--
+- The [Help](/documentation/help) guide provides a starting point and outlines common issues that you
+  may have.
+-->
+
+## Installation
+
+Install using `pip` from PyPI
+
+```bash
+pip install handsdown-fork
+```
+
+or directly from GitHub if you cannot wait to test new features
+
+```bash
+pip install git+https://github.com/FHPythonUtils/handsdown-fork.git
+```
+
+## Language information
+
+Using python 3.9, to 3.14
+
+## Working with the repo
+
+Clone, the repo with
+
+```bash
+git clone https://github.com/FHPythonUtils/handsdown-fork
+```
+
+Format
+
+```sh
+uv run ruff format
+```
+
+Linting
+
+```sh
+uv run ruff check
+uv run python3 -m basedpyright -p .
+```
+
+Testing
+
+```sh
+uv run python3 -m pytest
+```
+
+Alternatively use `tox` to run tests over a range of python versions
+
+```sh
+uvx tox
+```
+
+Documentation
+
+```sh
+uv run handsdown
+```
+
+## Community Files
+
+### Licence
+
+MIT License
+Copyright (c) FredHappyface
+Copyright (c) 2019 Vlad Emelianov
+(See the [LICENSE](/LICENSE) for more information.)
+
+<!-- ### Changelog
+
+See the [Changelog](/CHANGELOG.md) for more information. -->
+
+### Code of Conduct
+
+Online communities include people from many backgrounds. The *Project*
+contributors are committed to providing a friendly, safe and welcoming
+environment for all. Please see the
+[Code of Conduct](https://github.com/FHPythonUtils/.github/blob/master/CODE_OF_CONDUCT.md)
+ for more information.
+
+### Contributing
+
+Contributions are welcome, please see the
+[Contributing Guidelines](https://github.com/FHPythonUtils/.github/blob/master/CONTRIBUTING.md)
+for more information.
+
+### Security
+
+Thank you for improving the security of the project, please see the
+[Security Policy](https://github.com/FHPythonUtils/.github/blob/master/SECURITY.md)
+for more information.
+
+### Support
+
+Thank you for using this project, I hope it is of use to you. Please be aware that
+those involved with the project often do so for fun along with other commitments
+(such as work, family, etc). Please see the
+[Support Policy](https://github.com/FHPythonUtils/.github/blob/master/SUPPORT.md)
+for more information.