Merge branch 'release/3.0.0.0b1'

docs/conf.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 #
 # Configuration file for the Sphinx documentation builder.
 #
@@ -46,7 +45,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["myst_parser"]
+extensions = ["myst_parser", "sphinx_prompt"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = []

docs/usage.rst

@@ -3,9 +3,9 @@ Usage
 
 To apply the filter, use the following option with pandoc:
 
-.. code-block:: shell
+.. prompt:: bash
 
-   $ pandoc --filter pandoc-latex-tip
+    pandoc --filter pandoc-latex-tip
 
 Explanation
 -----------
@@ -94,9 +94,12 @@ Extensions
 
 Run ``pandoc-latex-tip`` for a complete explanation.
 
-..  code-block:: shell
+.. prompt:: bash
+
+    pandoc-latex-tip
+
+.. code-block:: console
 
-    $ pandoc-latex-tip
     pandoc-latex-tip filter (version number)
 
     Usage:
@@ -118,6 +121,7 @@ Run ``pandoc-latex-tip`` for a complete explanation.
       collections         List the collections
       help                Displays help for a command.
       icons               List the set of icons
+      info                Give information about pandoc-latex-tip
       latex               Run pandoc filter for LaTeX document
       list                Lists commands.
 
@@ -138,13 +142,28 @@ Demonstration: Using
 as input gives output file in
 `pdf <https://raw.githubusercontent.com/chdemko/pandoc-latex-tip/develop/docs/images/pandoc-latex-tip-sample.pdf>`__.
 
-..  code-block:: shell
+.. prompt:: bash
+
+    pandoc --filter pandoc-latex-tip pandoc-latex-tip-sample.txt \
+        -o pandoc-latex-tip-sample.pdf
+
+This command produces a PDF file with a warning since the icon named
+``mdi-account`` is not recognized.
+
+.. code-block:: console
 
-    $ pandoc --filter pandoc-latex-tip pandoc-latex-tip-sample.txt \
-    >    -o pandoc-latex-tip-sample.pdf
     [WARNING] pandoc-latex-tip: mdi-account is not a correct icon name
     [WARNING] Could not fetch resource unexisting.png: replacing image with description
-    $ pandoc-latex-tip icons
+
+It's possible to extend ``pandoc-latex-tip`` by defining a new collection
+containing ``CSS`` and ``TTF`` files:
+
+.. prompt:: bash
+
+    pandoc-latex-tip icons
+
+.. code-block:: console
+
     - collection: fontawesome
       CSS: fontawesome.css
       TTF: fa-solid-900.ttf
@@ -157,20 +176,47 @@ as input gives output file in
       CSS: brands.css
       TTF: fa-brands-400.ttf
       prefix: fab-
-    $ wget https://github.com/Templarian/MaterialDesign-Webfont/raw/v7.4.47/\
-    > css/materialdesignicons.css
-    $ wget https://github.com/Templarian/MaterialDesign-Webfont/raw/v7.4.47/\
-    > fonts/materialdesignicons-webfont.ttf
-    $ pandoc-latex-tip collections add materialdesign materialdesignicons.css
+
+.. prompt:: bash
+
+    wget https://github.com/Templarian/MaterialDesign-Webfont/raw/v7.4.47/\
+    css/materialdesignicons.css
+    wget https://github.com/Templarian/MaterialDesign-Webfont/raw/v7.4.47/\
+    fonts/materialdesignicons-webfont.ttf
+
+.. prompt:: bash
+
+        pandoc-latex-tip collections add materialdesign materialdesignicons.css
+
+.. code-block:: console
+
     Add file 'materialdesignicons.css' to collection 'materialdesign'
-    $ pandoc-latex-tip collections add materialdesign materialdesignicons-webfont.ttf
+
+.. prompt:: bash
+
+    pandoc-latex-tip collections add materialdesign materialdesignicons-webfont.ttf
+
+.. code-block:: console
+
     Add file 'materialdesignicons-webfont.ttf' to collection 'materialdesign'
-    $ pandoc-latex-tip icons add \
-    >     --CSS materialdesignicons.css \
-    >     --TTF materialdesignicons-webfont.ttf \
-    >     --prefix mdi- \
-    >     materialdesign
-    $ pandoc-latex-tip icons
+
+And by creating a new set of icons using a ``CSS`` file and a ``TTF`` file
+from a collection and by setting a prefix:
+
+.. prompt:: bash
+
+    pandoc-latex-tip icons add \
+        --CSS materialdesignicons.css \
+        --TTF materialdesignicons-webfont.ttf \
+        --prefix mdi- \
+        materialdesign
+
+.. prompt:: bash
+
+    pandoc-latex-tip icons
+
+.. code-block:: console
+
     - collection: fontawesome
       CSS: fontawesome.css
       TTF: fa-solid-900.ttf
@@ -187,11 +233,19 @@ as input gives output file in
       CSS: materialdesignicons.css
       TTF: materialdesignicons-webfont.ttf
       prefix: mdi-
-    $ pandoc --filter pandoc-latex-tip pandoc-latex-tip-sample.txt \
-    >     -o pandoc-latex-tip-sample.pdf
-    2 extra bytes in post.stringData array
-    [WARNING] Could not fetch resource unexisting.png: replacing image with description
 
+The original ``mdi-account`` unknown icon is now recognized by
+``pandoc-latex-tip``:
 
+.. prompt:: bash
 
+    pandoc --filter pandoc-latex-tip pandoc-latex-tip-sample.txt \
+        -o pandoc-latex-tip-sample.pdf
+
+.. code-block:: console
+
+    2 extra bytes in post.stringData array
+    [WARNING] Could not fetch resource unexisting.png: replacing image with description
 
+The ``2 extra bytes in post.stringData array`` message is due to an error
+in the ``TTF`` file from *materialdesign*.

pandoc_latex_tip/_app.py

@@ -11,6 +11,8 @@
 from cleo.commands.command import Command
 from cleo.helpers import argument, option
 
+import platformdirs
+
 import yaml
 
 
@@ -42,6 +44,46 @@
 )
 
 
+class InfoCommand(Command):
+    """
+    InfoCommand.
+    """
+
+    name = "info"
+    description = "Give information about pandoc-latex-tip"
+
+    def handle(self) -> int:
+        """
+        Handle info command.
+
+        Returns
+        -------
+        int
+            status code
+        """
+        self.line("<b>Installation</>")
+        self.line(
+            f"<info>Version</>:        <comment>" f"{version('pandoc-latex-tip')}"
+        )
+        self.line("")
+        self.line("<b>Environment</>")
+        self.line(
+            f"<info>Collection dir</>: <comment>"
+            f"{pathlib.Path(sys.prefix, 'share', 'pandoc_latex_tip')}</>"
+        )
+        self.line(
+            f"<info>Config file</>:    <comment>"
+            f"{pathlib.Path(sys.prefix, 'share', 'pandoc_latex_tip', 'config.yml')}</>"
+        )
+        self.line("")
+        self.line("<b>Cache</>")
+        self.line(
+            f"<info>Cache dir</>:      <comment>"
+            f"{platformdirs.AppDirs('pandoc_latex_tip').user_cache_dir}</>"
+        )
+        return 0
+
+
 class CollectionsAddCommand(Command):
     """
     CollectionsAddCommand.
@@ -69,6 +111,7 @@ def handle(self) -> int:
         ValueError
             If an error occurs.
         """
+        self.add_style("warning", fg="yellow", options=["bold"])
         if self.argument("name") == "fontawesome":
             raise ValueError("You cannot modify core collection")
         dir_path = pathlib.Path(
@@ -77,12 +120,14 @@ def handle(self) -> int:
         if not dir_path.exists():
             dir_path.mkdir(parents=True)
         file_path = pathlib.Path(self.argument("file"))
+        if file_path.suffix not in (".css", ".ttf"):
+            raise ValueError("The added file must be a CSS or TTF file")
         dest_path = pathlib.Path(dir_path, file_path.parts[-1])
         shutil.copy(file_path, dest_path)
 
         self.line(
-            f"Add file '{self.argument('file')}' to "
-            f"collection '{self.argument('name')}'"
+            f"Add file <comment>'{self.argument('file')}'</> to "
+            f"collection <warning>'{self.argument('name')}'</>"
         )
         return 0
 
@@ -114,6 +159,7 @@ def handle(self) -> int:
         ValueError
             If an error occurs.
         """
+        self.add_style("warning", fg="yellow", options=["bold"])
         name = self.argument("name")
         if name == "fontawesome":
             raise ValueError("You cannot modify core collection")
@@ -135,7 +181,7 @@ def handle(self) -> int:
             raise ValueError(f"Collection '{name}' does not exist")
 
         shutil.rmtree(dir_path)
-        self.line(f"Delete collection '{name}'")
+        self.line(f"Delete collection <warning>'{name}'</>")
         return 0
 
 
@@ -156,12 +202,14 @@ def handle(self) -> int:
         int
             status code
         """
+        self.add_style("warning", fg="yellow", options=["bold"])
         dir_path = pathlib.Path(sys.prefix, "share", "pandoc_latex_tip")
+        self.line("<b>Collections</>")
         for folder in dir_path.iterdir():
             if folder.parts[-1] == "fontawesome":
-                self.line("fontawesome *")
+                self.line("<error>fontawesome</>")
             elif folder.is_dir():
-                self.line(folder.parts[-1])
+                self.line(f"<warning>{folder.parts[-1]}</>")
         return 0
 
 
@@ -192,6 +240,7 @@ def handle(self) -> int:
         ValueError
             If an error occurs.
         """
+        self.add_style("warning", fg="yellow", options=["bold"])
         name = self.argument("name")
         dir_path = pathlib.Path(
             sys.prefix,
@@ -202,8 +251,26 @@ def handle(self) -> int:
         if not dir_path.exists():
             raise ValueError(f"Collection '{name}' does not exist")
 
+        self.line("<b>Information</>")
+        if name == "fontawesome":
+            self.line(f"<info>Name</>: <error>{name}</>")
+            self.line("<info>Type</>: <error>core</>")
+        else:
+            self.line(f"<info>Name</>: <warning>{name}</>")
+            self.line("<info>Type</>: <warning>additional</>")
+
+        self.line("")
+        self.line("<b>CSS files</>")
+        for filename in dir_path.iterdir():
+            if filename.suffix == ".css":
+                self.line(f"- <comment>{filename.parts[-1]}</>")
+
+        self.line("")
+        self.line("<b>TTF files</>")
         for filename in dir_path.iterdir():
-            self.line(filename.parts[-1])
+            if filename.suffix == ".ttf":
+                self.line(f"- <comment>{filename.parts[-1]}</>")
+
         return 0
 
 
@@ -359,6 +426,7 @@ def handle(self) -> int:
         int
             status code
         """
+        self.add_style("warning", fg="yellow", options=["bold"])
         icons = get_core_icons()
         config_path = pathlib.Path(
             sys.prefix,
@@ -369,8 +437,14 @@ def handle(self) -> int:
         if config_path.exists():
             with config_path.open(encoding="utf-8") as stream:
                 icons.extend(yaml.safe_load(stream))
-        self.line(yaml.dump(icons, sort_keys=False))
-
+        for element in icons:
+            if element["collection"] == "fontawesome":
+                self.line("- <info>collection</>: <error>fontawesome</>")
+            else:
+                self.line(f"- <info>collection</>: <warning>{element['collection']}</>")
+            self.line(f"  <info>CSS</>: <comment>{element['CSS']}</>")
+            self.line(f"  <info>TTF</>: <comment>{element['TTF']}</>")
+            self.line(f"  <info>prefix</>: <comment>{element['prefix']}</>")
         return 0
 
 
@@ -425,6 +499,7 @@ def app() -> None:
         version=version("pandoc-latex-tip"),
     )
     application.set_display_name("pandoc-latex-tip filter")
+    application.add(InfoCommand())
     application.add(CollectionsAddCommand())
     application.add(CollectionsDeleteCommand())
     application.add(CollectionsListCommand())

pyproject.toml

@@ -102,6 +102,7 @@ optional = true
 myst-parser = "^2.0"
 Sphinx = "^7.2.6"
 sphinx-rtd-theme = "^2.0.0"
+sphinx-prompt = "^1.8.0"
 
 [tool.poetry.scripts]
 pandoc-latex-tip = "pandoc_latex_tip:app"