From 5b68567ff6f9fdf9a3d3b725203a2649a1847b9d Mon Sep 17 00:00:00 2001 From: melissawm Date: Sat, 28 Jan 2023 13:02:03 -0300 Subject: [PATCH] Documentation improvements --- README.md | 8 +++-- docs/configuration.rst | 26 +++++++------- docs/dev/RELEASE.md | 15 -------- docs/dev/index.rst | 69 +++++++++++++++++++++++++++++++++++++ docs/index.rst | 2 +- docs/quickstart.rst | 2 -- src/sphinx_tags/__init__.py | 11 ++---- 7 files changed, 91 insertions(+), 42 deletions(-) delete mode 100644 docs/dev/RELEASE.md create mode 100644 docs/dev/index.rst diff --git a/README.md b/README.md index f39903e..283956c 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A tiny Sphinx extension that implements blog-style tags for documentation. -**🗣 If you use this extension in your project, please drop us a note [in this discussion post](https://github.com/melissawm/sphinx-tags/discussions/32)** +**🗣 If you use this extension in your project, please drop us a note [in this discussion post](https://github.com/melissawm/sphinx-tags/discussions/32)** ## Installation @@ -23,7 +23,7 @@ Refer to the [documentation](https://sphinx-tags.readthedocs.io/en/latest/) for ## Contributing -Feel free to submit issues or PRs - keep in mind this is experimental! +Feel free to submit issues or PRs - keep in mind this project is experimental! ### Setup for development @@ -43,6 +43,10 @@ sphinx-build docs docs/_build/html `sphinx-tags` uses [pre-commit](https://pre-commit.com/), and code is formatted according to [black](https://github.com/psf/black) +### Contribution guide + +If you want to submit Pull requests to this repository, please follow the [contribution guidelines](). + ## Code of Conduct All contributors and maintainers are expected to follow the diff --git a/docs/configuration.rst b/docs/configuration.rst index 285214c..8700ba7 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -1,32 +1,30 @@ .. _config: -Configuration for sphinx-tags -============================= +Configuration +============= A few custom configuration keys can be used in your ``conf.py`` file. - ``tags_create_tags`` - - Whether to process tags or not. Default: ``False`` + - Whether to process tags or not. **Default:** ``False`` - ``tags_output_dir`` - Output directory for the tags source files, relative to the project root. - Default: ``_tags`` + **Default:** ``_tags`` - ``tags_extension`` - A list of file extensions to inspect. Use ``"rst"`` if you are using pure Sphinx, and ``"md"`` if your are using MyST. Note that if you list both ``["md", "rst"]``, all generated pages to be created as Markdown files. - Default: ``["rst"]`` + **Default:** ``["rst"]`` +- ``tags_intro_text`` + - The string used on pages that have tags. **Default:** ``Tags`` - ``tags_page_title`` - - The title of the tag page, after which the tag is listed. - Default: ``Tag`` + - The title of the tag page, after which the tag is listed. **Default:** + ``My tags`` - ``tags_page_header`` - - The string after which the pages with the tag are listed. - Default: ``With this tag`` + - The string after which the pages with the tag are listed. **Default:** + ``With this tag`` - ``tags_index_head`` - - The string used as caption in the tagsindex file. - Default: ``Tags`` -- ``tags_intro_text`` - - The string used on pages that have tags. - Default: ``Tags`` + - The string used as caption in the tagsindex file. **Default:** ``Tags`` Tags overview page ------------------ diff --git a/docs/dev/RELEASE.md b/docs/dev/RELEASE.md deleted file mode 100644 index 44cbf66..0000000 --- a/docs/dev/RELEASE.md +++ /dev/null @@ -1,15 +0,0 @@ -# How to cut a release - -`sphinx-tags` uses [flit](https://github.com/pypa/flit) to manage releases. - -```{tags} development -``` - -To cut a new release: - -1. Make sure the version string in `src/sphinx_tags/__init__.py` is updated with - the release number you want. -2. Run `flit publish` to upload your new version to PyPI. -3. Run `git tag `, and `git push origin --tags` to update the tags on - GitHub. -4. Make a new release using the GitHub interface. diff --git a/docs/dev/index.rst b/docs/dev/index.rst new file mode 100644 index 0000000..823e33e --- /dev/null +++ b/docs/dev/index.rst @@ -0,0 +1,69 @@ +.. tags:: development + +Contribute +========== + +All contributions are welcome in ``sphinx-tags``! All contributors and +maintainers are expected to follow the `PSF Code of Conduct +`__. + + +If you want to point out existing problems or suggest enhancements to code or +documentation, please `open an issue on GitHub +`__. + +If you want to submit a Pull Request with a patch or new feature, make sure you +follow the guide below. + +Pull request guidelines +----------------------- + +1. **Set up your development environment** + + After cloning this repo and activating a virtual environment manager such as + `venv` or `conda`, use + + :: + + python -m pip install -e ".[sphinx]" + + To build the documentation locally, use + + :: + + sphinx-build docs docs/_build/html + +2. **Hack away!** + +3. **Style checks** + + ``sphinx-tags`` uses `pre-commit `__, and code is + formatted according to `black `__. To make sure + your code conforms to this style, you can: + + - Setup pre-commit for your local clone:: + + pre-commit install + + - Run pre-commit:: + + pre-commit run --all + + - Re-add any changed files to your staging area and run pre-commit again to + make sure any fixes are applied to your code. + +4. **Commit your changes and send your pull request as usual.** + +Releases +-------- + +``sphinx-tags`` uses `flit `__ to manage releases. + +To cut a new release: + +1. Make sure the version string in ``src/sphinx_tags/__init__.py`` is updated + with the release number you want. +2. Run ``flit publish`` to upload your new version to PyPI. +3. Run ``git tag ``, and ``git push origin --tags`` to update the tags + on GitHub. +4. Make a new release using the GitHub interface. diff --git a/docs/index.rst b/docs/index.rst index de85164..1d557f4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,7 +16,7 @@ documentation. quickstart configuration examples.md - dev/RELEASE.md + dev/index .. toctree:: :caption: Site tags diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 7ca95a7..7efaf87 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -23,8 +23,6 @@ Use pip or conda to install ``sphinx-tags``: .. tab-item:: conda - .. note:: This is not yet available. - .. code-block:: conda install -c conda-forge sphinx-tags diff --git a/src/sphinx_tags/__init__.py b/src/sphinx_tags/__init__.py index f611684..96a87e6 100644 --- a/src/sphinx_tags/__init__.py +++ b/src/sphinx_tags/__init__.py @@ -119,9 +119,7 @@ def create_file( for item in items: # We want here the filepath relative to /docs/_tags # pathlib does not support relative paths for two absolute paths - relpath = Path( - os.path.relpath(item.filepath, srcdir) - ).as_posix() + relpath = Path(os.path.relpath(item.filepath, srcdir)).as_posix() content.append(f"../{relpath}") content.append("```") else: @@ -138,9 +136,7 @@ def create_file( for item in sorted(items, key=lambda i: i.filepath): # We want here the filepath relative to /docs/_tags # pathlib does not support relative paths for two absolute paths - relpath = Path( - os.path.relpath(item.filepath, srcdir) - ).as_posix() + relpath = Path(os.path.relpath(item.filepath, srcdir)).as_posix() content.append(f" ../{relpath}") content.append("") @@ -279,8 +275,7 @@ def update_tags(app): logger.info("Tags updated", color="white") else: logger.info( - "Tags were not created (tags_create_tags=False in conf.py)", - color="white" + "Tags were not created (tags_create_tags=False in conf.py)", color="white" )