Merge pull request #41 from melissawm/docs-update

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

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

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
+<https://github.com/psf/community-code-of-conduct>`__.
+
+
+If you want to point out existing problems or suggest enhancements to code or
+documentation, please `open an issue on GitHub
+<https://github.com/melissawm/sphinx-tags/issues>`__.
+
+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 <https://pre-commit.com/>`__, and code is
+   formatted according to `black <https://github.com/psf/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 <https://github.com/pypa/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 <version>``, and ``git push origin --tags`` to update the tags
+   on GitHub.
+4. Make a new release using the GitHub interface.

docs/index.rst

@@ -16,7 +16,7 @@ documentation.
    quickstart
    configuration
    examples.md
-   dev/RELEASE.md
+   dev/index
 
 .. toctree::
    :caption: Site tags

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

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"
         )