Metadata-Version: 2.4
Name: sphinx-ape
Version: 0.1.0
Summary: sphinx-ape: Build Sphinx Documentation for ApeWorX plugins
Home-page: https://github.com/ApeWorX/sphinx-ape
Author: ApeWorX Ltd.
Author-email: admin@apeworx.io
License: Apache-2.0
Keywords: ethereum
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
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
Requires-Python: >=3.9,<4
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click<9,>=8.1.7
Requires-Dist: tomli<3,>=1.2.3
Requires-Dist: shibuya
Requires-Dist: pygments<3,>=2.17.0
Requires-Dist: myst-parser<5,>=4.0.0
Requires-Dist: sphinx-click<7,>=6.0.0
Requires-Dist: Sphinx<9,>=8.1.3
Requires-Dist: sphinx_rtd_theme<4,>=3.0.1
Requires-Dist: sphinxcontrib-napoleon<0.8,>=0.7
Requires-Dist: sphinx-plausible<0.2,>=0.1.2
Provides-Extra: test
Requires-Dist: pytest<9,>=8.3.2; extra == "test"
Requires-Dist: pytest-mock<4,>=3.14.0; extra == "test"
Provides-Extra: lint
Requires-Dist: black<25,>=24.10.0; extra == "lint"
Requires-Dist: mypy<2,>=1.13.0; extra == "lint"
Requires-Dist: types-setuptools; extra == "lint"
Requires-Dist: docutils-stubs; extra == "lint"
Requires-Dist: flake8<8,>=7.1.1; extra == "lint"
Requires-Dist: flake8-breakpoint<2,>=1.1.0; extra == "lint"
Requires-Dist: flake8-print<6,>=5.0.0; extra == "lint"
Requires-Dist: flake8-pydantic; extra == "lint"
Requires-Dist: flake8-type-checking; extra == "lint"
Requires-Dist: isort<6,>=5.13.2; extra == "lint"
Requires-Dist: mdformat>=0.7.19; extra == "lint"
Requires-Dist: mdformat-gfm>=0.3.5; extra == "lint"
Requires-Dist: mdformat-frontmatter>=0.4.1; extra == "lint"
Requires-Dist: mdformat-pyproject>=0.0.2; extra == "lint"
Provides-Extra: release
Requires-Dist: setuptools>=75.6.0; extra == "release"
Requires-Dist: wheel; extra == "release"
Requires-Dist: twine; extra == "release"
Provides-Extra: dev
Requires-Dist: black<25,>=24.10.0; extra == "dev"
Requires-Dist: mypy<2,>=1.13.0; extra == "dev"
Requires-Dist: types-setuptools; extra == "dev"
Requires-Dist: docutils-stubs; extra == "dev"
Requires-Dist: flake8<8,>=7.1.1; extra == "dev"
Requires-Dist: flake8-breakpoint<2,>=1.1.0; extra == "dev"
Requires-Dist: flake8-print<6,>=5.0.0; extra == "dev"
Requires-Dist: flake8-pydantic; extra == "dev"
Requires-Dist: flake8-type-checking; extra == "dev"
Requires-Dist: isort<6,>=5.13.2; extra == "dev"
Requires-Dist: mdformat>=0.7.19; extra == "dev"
Requires-Dist: mdformat-gfm>=0.3.5; extra == "dev"
Requires-Dist: mdformat-frontmatter>=0.4.1; extra == "dev"
Requires-Dist: mdformat-pyproject>=0.0.2; extra == "dev"
Requires-Dist: setuptools>=75.6.0; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest<9,>=8.3.2; extra == "dev"
Requires-Dist: pytest-mock<4,>=3.14.0; extra == "dev"
Requires-Dist: commitizen; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest-watch; extra == "dev"
Requires-Dist: IPython; extra == "dev"
Requires-Dist: ipdb; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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.
