From 9a5504242a1e77043dc4bf3579b46ddf15aed832 Mon Sep 17 00:00:00 2001 From: nebelgrau77 Date: Fri, 7 Oct 2022 19:46:02 +0200 Subject: [PATCH] added alphabetic sorting and tag naming configuration, edited docs --- CHANGELOG.md | 5 +++++ docs/configuration.rst | 9 ++++++++ src/sphinx_tags/__init__.py | 43 +++++++++++++++++++++++-------------- 3 files changed, 41 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6ca6747..13c5ea6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,8 @@ Version 0.1 (August 23, 2022) - Includes support for MyST and sphinx-gallery + +Version 0.1.6 (October 7, 2022) + +- Added page title and header as a parameter +- Alphabetic sorting of tags \ No newline at end of file diff --git a/docs/configuration.rst b/docs/configuration.rst index 7d4c0c6..d2b2c6c 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -15,6 +15,15 @@ A few custom configuration keys can be used in your ``conf.py`` file. 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"]`` +- ``tags_page_title`` + - The title of the tag page, after which the tag is listed. + Default: ``Tag`` +- ``tags_page_header`` + - 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 overview page ------------------ diff --git a/src/sphinx_tags/__init__.py b/src/sphinx_tags/__init__.py index 824b1e4..2a9bc95 100644 --- a/src/sphinx_tags/__init__.py +++ b/src/sphinx_tags/__init__.py @@ -7,7 +7,7 @@ from docutils import nodes from pathlib import Path -__version__ = "0.1.5" +__version__ = "0.1.6" logger = getLogger("sphinx-tags") @@ -28,7 +28,7 @@ class TagLinks(SphinxDirective): # Custom attributes separator = "," - intro_text = "Tags: " + intro_text = "In categories: " def run(self): tags = [arg.replace(self.separator, "") for arg in self.arguments] @@ -66,7 +66,7 @@ def __init__(self, name): self.name = name self.items = [] - def create_file(self, items, extension, tags_output_dir, srcdir): + def create_file(self, items, extension, tags_output_dir, srcdir, tags_page_title, tags_page_header): """Create file with list of documents associated with a given tag in toctree format. @@ -86,17 +86,22 @@ def create_file(self, items, extension, tags_output_dir, srcdir): list of file extensions used. srcdir : str root folder for the documentation (usually, project/docs) + tags_page_title: str + the title of the tag page, after which the tag is listed (e.g. "Tag: ...") + tags_page_header: str + the words after which the pages with the tag are listed, e.g. "With this tag") + """ content = [] if "md" in extension: filename = f"{self.name}.md" - content.append(f"# Tag: {self.name}") + content.append(f"# {tags_page_title}: {self.name}") content.append("") content.append("```{toctree}") - content.append("---") + content.append("--------") content.append("maxdepth: 1") - content.append("caption: With this tag") + content.append(f"caption: {tags_page_header}") content.append("---") # items is a list of files associated with this tag for item in items: @@ -106,16 +111,16 @@ def create_file(self, items, extension, tags_output_dir, srcdir): content.append("```") else: filename = f"{self.name}.rst" - content.append(f"Tag: {self.name}") - content.append("#" * len(self.name) + "#####") + content.append(f"{tags_page_title}: {self.name}") + content.append("#" * (len(self.name) + len(tags_page_title) + 2)) content.append("") # Return link block at the start of the page""" content.append(".. toctree::") content.append(" :maxdepth: 1") - content.append(" :caption: With this tag") + content.append(f" :caption: {tags_page_header}") content.append("") # items is a list of files associated with this tag - for item in items: + for item in sorted(items, key=lambda i: i.filepath): # We want here the filepath relative to /docs/_tags relpath = item.filepath.relative_to(srcdir) content.append(f" ../{relpath}") @@ -155,7 +160,7 @@ def assign_to_tags(self, tag_dict): tag_dict[tag].items.append(self) -def tagpage(tags, outdir, title, extension): +def tagpage(tags, outdir, title, extension, tags_index_head): """Creates Tag overview page. This page contains a list of all available tags. @@ -172,10 +177,10 @@ def tagpage(tags, outdir, title, extension): # toctree for this page content.append("```{toctree}") content.append("---") - content.append("caption: Tags") + content.append(f"caption: {tags_index_head}") content.append("maxdepth: 1") content.append("---") - for tag in tags: + for tag in sorted(tags, key = lambda t: t.name): content.append(f"{tag.name} ({len(tag.items)}) <{tag.name}>") content.append("```") content.append("") @@ -191,10 +196,10 @@ def tagpage(tags, outdir, title, extension): content.append("") # toctree for the page content.append(".. toctree::") - content.append(" :caption: Tags") + content.append(f" :caption: {tags_index_head}") content.append(" :maxdepth: 1") content.append("") - for tag in tags: + for tag in sorted(tags, key = lambda t: t.name): content.append(f" {tag.name} ({len(tag.items)}) <{tag.name}.rst>") content.append("") filename = os.path.join(outdir, "tagsindex.rst") @@ -232,6 +237,8 @@ def update_tags(app): app.config.tags_extension, tags_output_dir, app.srcdir, + app.config.tags_page_title, + app.config.tags_page_header ) # Create tags overview page tagpage( @@ -239,6 +246,7 @@ def update_tags(app): os.path.join(app.srcdir, tags_output_dir), app.config.tags_overview_title, app.config.tags_extension, + app.config.tags_index_head ) logger.info("Tags updated", color="white") else: @@ -257,7 +265,10 @@ def setup(app): app.add_config_value("tags_output_dir", "_tags", "html") app.add_config_value("tags_overview_title", "Tags overview", "html") app.add_config_value("tags_extension", ["rst"], "html") - # internal config values + app.add_config_value("tags_page_title", "My tags", "html") + app.add_config_value("tags_page_header", "With this tag", "html") + app.add_config_value("tags_index_head", "Tags", "html") + # internal config values app.add_config_value( "remove_from_toctrees", [