Merge pull request #27 from nebelgrau77/main

.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/_tags/
 .DS_Store
 
 # PyBuilder

CHANGELOG.md

@@ -1,3 +1,10 @@
 Version 0.1 (August 23, 2022)
 
 - Includes support for MyST and sphinx-gallery
+
+Version 0.1.6 (October 9, 2022)
+
+- Added page title and header as a parameter
+- Alphabetic sorting of tags
+- Added removal of all .md and .rst files in the tag folder before generating them again (avoids having duplicates after removing/changing some tag)
+- Tag intro text as a parameter

docs/Makefile

@@ -16,7 +16,8 @@ help:
 
 clean:
 	rm -rf _build/
-	rm -rf _tags
+
+# rm -rf _tags
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/conf.py

@@ -42,6 +42,10 @@
 # tags_output_dir = "_tags"  # default
 tags_overview_title = "All tags"  # default: "Tags overview"
 tags_extension = ["rst", "md"]  # default: ["rst"]
+tags_intro_text = "Tags in this page:"  # default: "Tags:"
+tags_page_title = "All my tags"  # default: "My tags:"
+tags_page_header = "Pages with this tag"  # default: "With this tag"
+tags_index_head = "Tags in this site"  # default: "Tags"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/configuration.rst

@@ -15,6 +15,18 @@ 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_intro_text``
+  - The string used on pages that have tags.
+  Default: ``Tags``
 
 Tags overview page
 ------------------

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,14 +28,14 @@ class TagLinks(SphinxDirective):
 
     # Custom attributes
     separator = ","
-    intro_text = "Tags: "
 
     def run(self):
         tags = [arg.replace(self.separator, "") for arg in self.arguments]
         result = nodes.paragraph()
         result["classes"] = ["tags"]
-        result += nodes.inline(text=self.intro_text)
+        result += nodes.inline(text=f"{self.env.app.config.tags_intro_text} ")
         count = 0
+
         for tag in tags:
             count += 1
             # We want the link to be the path to the _tags folder, relative to this document's path
@@ -47,10 +47,12 @@ def run(self):
             #   |
             #    - current_doc_path
             docpath = Path(self.env.doc2path(self.env.docname)).parent
+
             rootdir = os.path.relpath(
                 os.path.join(self.env.app.srcdir, self.env.app.config.tags_output_dir),
                 docpath,
             )
+
             link = os.path.join(rootdir, f"{tag}.html")
             tag_node = nodes.reference(refuri=link, text=tag)
             result += tag_node
@@ -66,7 +68,15 @@ 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 +96,24 @@ 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: programming")
+        tags_page_header: str
+            the words after which the pages with the tag are listed, e.g. "With this tag: Hello World")
+        tag_intro_text: str
+            the words after which the tags of a given page are listed, e.g. "Tags: programming, python")
+
 
         """
         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("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 +123,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 +172,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 +189,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 +208,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")
@@ -220,10 +237,16 @@ def assign_entries(app):
 def update_tags(app):
     """Update tags according to pages found"""
     if app.config.tags_create_tags:
+
         tags_output_dir = Path(app.config.tags_output_dir)
+
         if not os.path.exists(os.path.join(app.srcdir, tags_output_dir)):
             os.makedirs(os.path.join(app.srcdir, tags_output_dir))
 
+        for file in os.listdir(os.path.join(app.srcdir, tags_output_dir)):
+            if file.endswith("md") or file.endswith("rst"):
+                os.remove(os.path.join(app.srcdir, tags_output_dir, file))
+
         # Create pages for each tag
         tags, pages = assign_entries(app)
         for tag in tags.values():
@@ -232,13 +255,16 @@ 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(
             tags,
             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,6 +283,11 @@ 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")
+    app.add_config_value("tags_intro_text", "Tags:", "html")
+    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",