.github/workflows/docs.yml

@@ -17,22 +17,21 @@ jobs:
         uses: actions/setup-python@v3
         with:
           python-version: "3.x"
-      - name: Install package and dependencies
-        run: pip install .[doc_build]
+      - name: Install dependencies
+        run: pip install sphinx sphinx_rtd_theme sphinx-autodoc-typehints myst-parser
       - name: Generate Class List
-        run: python ./docs/source/generate_class_list.py
+        run: |
+          pip install .
+          python ./docs/source/generate_class_list.py
       - name: Build Docs
         run: |
-          mkdir -p docs/source/media
-          cp media/* docs/source/media/
-          mkdir -p docs/source/tests
-          cp tests/test_rendering_example*.py docs/source/tests/
-          cp LICENSE docs/source/LICENSE.md
           cd docs
           sphinx-apidoc -o source/ ../src/ -M --no-toc
           rm source/*.rst
           make html
           touch build/html/.nojekyll
+          mkdir -p build/html/media
+          cp ../media/output_example.png build/html/media/
 
       - name: Deploy to GitHub Pages
         uses: JamesIves/github-pages-deploy-action@v4

.gitignore

@@ -69,8 +69,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/build/
-docs/source/_autogenerated/
+docs/_build/
 
 # PyBuilder
 .pybuilder/
@@ -133,3 +132,6 @@ pyModbusTCP_old/
 test.py
 test_*.ipynb
 settings.json
+
+# Autogenerated doc file
+docs/source/modules.md

docs/source/conf.py

@@ -26,8 +26,7 @@ exclude_patterns = []
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 # html_theme = 'alabaster'
-html_theme = 'pydata_sphinx_theme'
+html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
 
 autodoc_inherit_docstrings = True
-autoclass_content = 'both'

docs/source/generate_class_list.py

@@ -2,11 +2,10 @@ import importlib
 import inspect
 import fnmatch
 from io import TextIOWrapper
-import os
 
 
 def write_classes(f: TextIOWrapper, patterns: list[str], module_name: str, title: str, description: str = '', exclude: list[str] = []) -> None:
-    """Write the classes to the file."""
+
     module = importlib.import_module(module_name)
 
     classes = [
@@ -16,63 +15,47 @@ def write_classes(f: TextIOWrapper, patterns: list[str], module_name: str, title
             obj.__doc__ and '(Automatic generated stub)' not in obj.__doc__)
     ]
 
+    """Write the classes to the file."""
+    f.write(f'## {title}\n\n')
     if description:
         f.write(f'{description}\n\n')
 
-    write_dochtree(f, title, classes)
-
     for cls in classes:
-        with open(f'docs/source/_autogenerated/{cls}.md', 'w') as f2:
-            f2.write(f'# {module_name}.{cls}\n')
-            f2.write('```{eval-rst}\n')
-            f2.write(f'.. autoclass:: {module_name}.{cls}\n')
-            f2.write('   :members:\n')
-            f2.write('   :undoc-members:\n')
-            f2.write('   :show-inheritance:\n')
-            f2.write('   :inherited-members:\n')
-            f2.write('```\n\n')
+        f.write('```{eval-rst}\n')
+        f.write(f'.. autoclass:: {module_name}.{cls}\n')
+        f.write('   :members:\n')
+        f.write('   :undoc-members:\n')
+        f.write('   :show-inheritance:\n')
+        f.write('   :inherited-members:\n')
+        if title != 'Base classes':
+            f.write('   :exclude-members: select\n')
+        f.write('```\n\n')
 
 
 def write_functions(f: TextIOWrapper, patterns: list[str], module_name: str, title: str, description: str = '', exclude: list[str] = []) -> None:
-    """Write the classes to the file."""
+
     module = importlib.import_module(module_name)
 
-    functions = [
+    classes = [
         name for name, obj in inspect.getmembers(module, inspect.isfunction)
         if (obj.__module__ == module_name and
             any(fnmatch.fnmatch(name, pat) for pat in patterns if pat not in exclude))
     ]
 
+    """Write the classes to the file."""
+    f.write(f'## {title}\n\n')
     if description:
         f.write(f'{description}\n\n')
 
-    write_dochtree(f, title, functions)
-
-    for func in functions:
+    for func in classes:
         if not func.startswith('_'):
-            with open(f'docs/source/_autogenerated/{func}.md', 'w') as f2:
-                f2.write(f'# {module_name}.{func}\n')
-                f2.write('```{eval-rst}\n')
-                f2.write(f'.. autofunction:: {module_name}.{func}\n')
-                f2.write('```\n\n')
+            f.write('```{eval-rst}\n')
+            f.write(f'.. autofunction:: {module_name}.{func}\n')
+            f.write('```\n\n')
 
 
-def write_dochtree(f: TextIOWrapper, title: str, items: list[str]):
-    f.write('```{toctree}\n')
-    f.write(':maxdepth: 1\n')
-    f.write(f':caption: {title}:\n')
-    for text in items:
-        if not text.startswith('_'):
-            f.write(f"{text}\n")
-    f.write('```\n\n')
-
-
-if __name__ == "__main__":
-    # Ensure the output directory exists
-    os.makedirs('docs/source/_autogenerated', exist_ok=True)
-
-    with open('docs/source/_autogenerated/index.md', 'w') as f:
-        f.write('# Classes and functions\n\n')
-        write_classes(f, ['DocumentWriter'], 'pyladoc', title='DocumentWriter Class')
-        write_functions(f, ['*'], 'pyladoc', title='Functions')
-        write_functions(f, ['*'], 'pyladoc.latex', title='Submodule latex')
+with open('docs/source/modules.md', 'w') as f:
+    f.write('# Pyladoc classes, functions and submodules\n\n')
+    write_classes(f, ['DocumentWriter'], 'pyladoc', title='DocumentWriter Class')
+    write_functions(f, ['*'], 'pyladoc', title='Functions')
+    write_functions(f, ['*'], 'pyladoc.latex', title='Submodule latex')

docs/source/index.md

@@ -1,7 +1,9 @@
 ```{toctree}
-:maxdepth: 1
-:hidden:
-_autogenerated/index
+:maxdepth: 2
+:caption: Contents:
+
+readme
+modules
 ```
 
 ```{include} ../../README.md

docs/source/readme.md

@@ -0,0 +1,2 @@
+```{include} ../../README.md
+```

pyproject.toml

@@ -24,12 +24,6 @@ dev = [
     "matplotlib>=3.1.1",
     "pandas>=2.0.0", "Jinja2",
 ]
-doc_build = [
-  "sphinx",
-  "pydata_sphinx_theme",
-  "sphinx-autodoc-typehints",
-  "myst-parser"
-]
 
 [project.urls]
 Homepage = "https://github.com/Nonannet/pyladoc"

src/pyladoc/latex.py

@@ -18,6 +18,10 @@ else:
 LatexEngine = Literal['pdflatex', 'lualatex', 'xelatex', 'tectonic']
 
 
+def basic_formatter(value: Any) -> str:
+    return escape_text(str(value))
+
+
 def to_ascii(text: str) -> str:
     """
     Replaces/escapes often used unicode characters in LaTeX code or text
@@ -317,17 +321,6 @@ def compile(latex_code: str, output_file: str = '', encoding: str = 'utf-8', eng
 
 
 def inject_latex_command(text: str, command: str) -> str:
-    """
-    Injects a provided LaTeX code under the last line
-    starting with \\usepackage.
-
-    Args:
-        text: input LaTeX code
-        command: code to inject
-
-    Returns:
-        LaTeX code with injected command
-    """
     lines = text.splitlines()
 
     last_package_index = -1