diff --git a/docs/conf.py b/docs/conf.py index 664b4a4..51f31b6 100644 --- a/docs/conf.py +++ b/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 = [] diff --git a/docs/usage.rst b/docs/usage.rst index e4c3497..20fca51 100644 --- a/docs/usage.rst +++ b/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 `__. -.. 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*. diff --git a/pandoc_latex_tip/_app.py b/pandoc_latex_tip/_app.py index 67de3dd..df8565e 100644 --- a/pandoc_latex_tip/_app.py +++ b/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("Installation") + self.line( + f"Version: " f"{version('pandoc-latex-tip')}" + ) + self.line("") + self.line("Environment") + self.line( + f"Collection dir: " + f"{pathlib.Path(sys.prefix, 'share', 'pandoc_latex_tip')}" + ) + self.line( + f"Config file: " + f"{pathlib.Path(sys.prefix, 'share', 'pandoc_latex_tip', 'config.yml')}" + ) + self.line("") + self.line("Cache") + self.line( + f"Cache dir: " + 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 '{self.argument('file')}' to " + f"collection '{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 '{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("Collections") for folder in dir_path.iterdir(): if folder.parts[-1] == "fontawesome": - self.line("fontawesome *") + self.line("fontawesome") elif folder.is_dir(): - self.line(folder.parts[-1]) + self.line(f"{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("Information") + if name == "fontawesome": + self.line(f"Name: {name}") + self.line("Type: core") + else: + self.line(f"Name: {name}") + self.line("Type: additional") + + self.line("") + self.line("CSS files") + for filename in dir_path.iterdir(): + if filename.suffix == ".css": + self.line(f"- {filename.parts[-1]}") + + self.line("") + self.line("TTF files") for filename in dir_path.iterdir(): - self.line(filename.parts[-1]) + if filename.suffix == ".ttf": + self.line(f"- {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("- collection: fontawesome") + else: + self.line(f"- collection: {element['collection']}") + self.line(f" CSS: {element['CSS']}") + self.line(f" TTF: {element['TTF']}") + self.line(f" prefix: {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()) diff --git a/poetry.lock b/poetry.lock index 5c247e1..8fb1bde 100644 --- a/poetry.lock +++ b/poetry.lock @@ -2181,6 +2181,22 @@ docs = ["sphinxcontrib-websupport"] lint = ["flake8 (>=6.0)", "importlib-metadata (>=6.0)", "mypy (==1.10.1)", "pytest (>=6.0)", "ruff (==0.5.2)", "sphinx-lint (>=0.9)", "tomli (>=2)", "types-docutils (==0.21.0.20240711)", "types-requests (>=2.30.0)"] test = ["cython (>=3.0)", "defusedxml (>=0.7.1)", "pytest (>=8.0)", "setuptools (>=70.0)", "typing_extensions (>=4.9)"] +[[package]] +name = "sphinx-prompt" +version = "1.8.0" +description = "Sphinx directive to add unselectable prompt" +optional = false +python-versions = ">=3.9,<4.0" +files = [ + {file = "sphinx_prompt-1.8.0-py3-none-any.whl", hash = "sha256:369ecc633f0711886f9b3a078c83264245be1adf46abeeb9b88b5519e4b51007"}, + {file = "sphinx_prompt-1.8.0.tar.gz", hash = "sha256:47482f86fcec29662fdfd23e7c04ef03582714195d01f5d565403320084372ed"}, +] + +[package.dependencies] +docutils = "*" +pygments = "*" +Sphinx = ">=7.0.0,<8.0.0" + [[package]] name = "sphinx-rtd-theme" version = "2.0.0" @@ -2550,4 +2566,4 @@ files = [ [metadata] lock-version = "2.0" python-versions = ">=3.10,<3.13" -content-hash = "be39cafcaa7137cce73033f18df78d601b11862283c3786130bc415dcea770c1" +content-hash = "3b4446e45d7e5c7d07a4ed76cc9abd6392a49d7b4e20c2490f3143faa64fef27" diff --git a/pyproject.toml b/pyproject.toml index 60809c8..0d9a31e 100644 --- a/pyproject.toml +++ b/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"