# Overview
`sphinx-ape` is a documentation plugin for the Sphinx framework.
The purpose of this plugin to share code for generating documentation across all ApeWorX repositories.
## Dependencies
- [python3](https://www.python.org/downloads) version 3.9 up to 3.12.
## Install
Install the package from GitHub:
```sh
pip install git+https://github.com/ApeWorX/sphinx-ape.git@main
```
**NOTE**: Also, you may clone and the package first and install locally.
Try `sphinx-ape --help` to check if it's installed.
## Quick Usage
To use this sphinx plugin, first generate the docs structure (ran from your project directory):
```sh
sphinx-ape init .
```
It will have generated a `docs/` folder with some necessary config file in it, along with a quick-start that links to your `README.md`.
Now, you can begin writing your Sphinx documentation.
There are three directories you can place documentation sources in:
1. `userguides/` - a directory containing how-to guides for how to use your package.
2. `commands/` - `.rst` files for the `sphinx-click` plugin for CLI-based references.
3. `methoddocs/` - Autodoc `.rst` files controlling your generated method documentation.
Once you have developed your documentation, ensure you have `sphinx-ape` installed.
For example, clone this repo and install it using `pip install <path/to/sphinx-ape>` or install from `pypi` by doing `pip intall sphinx-ape`.
After `sphinx-ape` is installed, build your projects' documentation by doing:
```sh
sphinx-ape build <path/to/project>
```
Most commonly, you will already be in your project's directory, so you will do:
```sh
sphinx-ape build .
```
Then, to view the documentation, run the `serve` command:
```sh
sphinx-ape serve <path/to/project>
# When in directory already
sphinx-ape serve .
```
To automatically open a browser at the same time as serving, use the `--open` flag:
```sh
sphinx-ape serve . --open
```
To run your doc-tests, use the `sphinx-ape test` command:
```sh
sphinx-ape test .
```
## Auto-TOC Tree
The `sphinx-ape init` command creates an `index.rst` file.
This file represents the table of contents for the docs site.
Any files not included in the TOC are not included in the documentation.
`sphinx-ape` generates a simple default file with the contents:
```rst
.. dynamic-toc-tree::
```
To customize the files included in the TOC, specify each respective guide-set name (e.g. `userguides`).
Also use this feature to control the ordering of the guides; otherwise the default is to include all guides in the directory in alphabetized order.
```rst
.. dynamic-toc-tree::
:userguides: guide0, guide1, final
```
You can also specify the guides in a list pattern:
```rst
.. dynamic-toc-tree::
:userguides:
- quickstart
- guide0
- guide1
- final
```
## GitHub Action
This GitHub action is meant for building the documentation in both core Ape as well any Ape plugin.
The action may also work for regular Python packages with a documentation-strategy similar to Ape.
There are three GitHub events that trigger this action:
1. Push to 'main': we build into 'latest/'.
The GitHub action will commit these changes to the 'gh-pages' branch.
2. Release: we copy 'latest/' into the release dir, as well as to 'stable/'.
The GitHub action will commit these changes to the 'gh-pages' branch.
3. Pull requests or local development: We ensure a successful build.
## GitHub Pages
To set up this action with GitHub pages for the release-workflow to work, first create a branch named `gh-pages` and push it to GitHub.
Then, delete everything besides a simple `README.md`, the `.gitignore` file, and the `LICENSE` file.
Once that is all pushed, verify on the Pages tab that a site was made for you.
Now, on merges to main and releases, this site should be updated (if you are using the action).
To publish the docs locally, use the `publish` command:
```sh
sphinx-ape publish .
```
## Development
Please see the [contributing guide](CONTRIBUTING.md) to learn more how to contribute to this project.
Comments, questions, criticisms and pull requests are welcomed.
Raw data
{
"_id": null,
"home_page": "https://github.com/ApeWorX/sphinx-ape",
"name": "sphinx-ape",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.9",
"maintainer_email": null,
"keywords": "ethereum",
"author": "ApeWorX Ltd.",
"author_email": "admin@apeworx.io",
"download_url": "https://files.pythonhosted.org/packages/67/8b/7c2366dad716c372d82c61a974fdeae91b2b6a0855448df1930c31c6b3d3/sphinx-ape-0.1.0a3.tar.gz",
"platform": null,
"description": "# Overview\n\n`sphinx-ape` is a documentation plugin for the Sphinx framework.\nThe purpose of this plugin to share code for generating documentation across all ApeWorX repositories.\n\n## Dependencies\n\n- [python3](https://www.python.org/downloads) version 3.9 up to 3.12.\n\n## Install\n\nInstall the package from GitHub:\n\n```sh\npip install git+https://github.com/ApeWorX/sphinx-ape.git@main\n```\n\n**NOTE**: Also, you may clone and the package first and install locally.\n\nTry `sphinx-ape --help` to check if it's installed.\n\n## Quick Usage\n\nTo use this sphinx plugin, first generate the docs structure (ran from your project directory):\n\n```sh\nsphinx-ape init .\n```\n\nIt will have generated a `docs/` folder with some necessary config file in it, along with a quick-start that links to your `README.md`.\n\nNow, you can begin writing your Sphinx documentation.\nThere are three directories you can place documentation sources in:\n\n1. `userguides/` - a directory containing how-to guides for how to use your package.\n2. `commands/` - `.rst` files for the `sphinx-click` plugin for CLI-based references.\n3. `methoddocs/` - Autodoc `.rst` files controlling your generated method documentation.\n\nOnce you have developed your documentation, ensure you have `sphinx-ape` installed.\nFor example, clone this repo and install it using `pip install <path/to/sphinx-ape>` or install from `pypi` by doing `pip intall sphinx-ape`.\n\nAfter `sphinx-ape` is installed, build your projects' documentation by doing:\n\n```sh\nsphinx-ape build <path/to/project>\n```\n\nMost commonly, you will already be in your project's directory, so you will do:\n\n```sh\nsphinx-ape build .\n```\n\nThen, to view the documentation, run the `serve` command:\n\n```sh\nsphinx-ape serve <path/to/project>\n# When in directory already\nsphinx-ape serve .\n```\n\nTo automatically open a browser at the same time as serving, use the `--open` flag:\n\n```sh\nsphinx-ape serve . --open\n```\n\nTo run your doc-tests, use the `sphinx-ape test` command:\n\n```sh\nsphinx-ape test .\n```\n\n## Auto-TOC Tree\n\nThe `sphinx-ape init` command creates an `index.rst` file.\nThis file represents the table of contents for the docs site.\nAny files not included in the TOC are not included in the documentation.\n`sphinx-ape` generates a simple default file with the contents:\n\n```rst\n.. dynamic-toc-tree::\n```\n\nTo customize the files included in the TOC, specify each respective guide-set name (e.g. `userguides`).\nAlso use this feature to control the ordering of the guides; otherwise the default is to include all guides in the directory in alphabetized order.\n\n```rst\n.. dynamic-toc-tree::\n :userguides: guide0, guide1, final\n```\n\nYou can also specify the guides in a list pattern:\n\n```rst\n.. dynamic-toc-tree::\n :userguides:\n - quickstart \n - guide0\n - guide1\n - final\n```\n\n## GitHub Action\n\nThis GitHub action is meant for building the documentation in both core Ape as well any Ape plugin.\nThe action may also work for regular Python packages with a documentation-strategy similar to Ape.\n\nThere are three GitHub events that trigger this action:\n\n1. Push to 'main': we build into 'latest/'.\n The GitHub action will commit these changes to the 'gh-pages' branch.\n\n2. Release: we copy 'latest/' into the release dir, as well as to 'stable/'.\n The GitHub action will commit these changes to the 'gh-pages' branch.\n\n3. Pull requests or local development: We ensure a successful build.\n\n## GitHub Pages\n\nTo set up this action with GitHub pages for the release-workflow to work, first create a branch named `gh-pages` and push it to GitHub.\nThen, delete everything besides a simple `README.md`, the `.gitignore` file, and the `LICENSE` file.\nOnce that is all pushed, verify on the Pages tab that a site was made for you.\nNow, on merges to main and releases, this site should be updated (if you are using the action).\n\nTo publish the docs locally, use the `publish` command:\n\n```sh\nsphinx-ape publish .\n```\n\n## Development\n\nPlease see the [contributing guide](CONTRIBUTING.md) to learn more how to contribute to this project.\nComments, questions, criticisms and pull requests are welcomed.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "sphinx-ape: Build Sphinx Documentation for ApeWorX plugins",
"version": "0.1.0a3",
"project_urls": {
"Homepage": "https://github.com/ApeWorX/sphinx-ape"
},
"split_keywords": [
"ethereum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "079ade2d506de9a040969c913fe5b78c0fed110b75eca9304ec681d590e82d1d",
"md5": "c5792dd174e0fbf59a6b4d40ba34454b",
"sha256": "f33fc5d24de4d025df4fda212e336d864d06763141b0a6e5252503bfd0eca1c2"
},
"downloads": -1,
"filename": "sphinx_ape-0.1.0a3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c5792dd174e0fbf59a6b4d40ba34454b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.9",
"size": 62224,
"upload_time": "2024-10-15T17:38:46",
"upload_time_iso_8601": "2024-10-15T17:38:46.566982Z",
"url": "https://files.pythonhosted.org/packages/07/9a/de2d506de9a040969c913fe5b78c0fed110b75eca9304ec681d590e82d1d/sphinx_ape-0.1.0a3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "678b7c2366dad716c372d82c61a974fdeae91b2b6a0855448df1930c31c6b3d3",
"md5": "703658392111c55daf034727e7251ecc",
"sha256": "2433d46865a00a784a3edf884823d820976a494ad5c1587986890bea104ff2f1"
},
"downloads": -1,
"filename": "sphinx-ape-0.1.0a3.tar.gz",
"has_sig": false,
"md5_digest": "703658392111c55daf034727e7251ecc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.9",
"size": 70347,
"upload_time": "2024-10-15T17:38:48",
"upload_time_iso_8601": "2024-10-15T17:38:48.428317Z",
"url": "https://files.pythonhosted.org/packages/67/8b/7c2366dad716c372d82c61a974fdeae91b2b6a0855448df1930c31c6b3d3/sphinx-ape-0.1.0a3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-15 17:38:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ApeWorX",
"github_project": "sphinx-ape",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-ape"
}
JSON
