Merge branch 'main' into tkp/zm

Author: timkpaine

.github/workflows/docs.yml

@@ -1,30 +1,15 @@
 name: Docs
-
 on:
   push:
-    branches:
-      - main
-    tags:
-      - v*
-    paths-ignore:
-      - LICENSE
-      - README.md
-
+    branches: ["main"]
+    tags: ["v*"]
+    paths-ignore: ["LICENSE", "README.md"]
 permissions:
     contents: write
-
 jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-      - run: pip install .
-      - run: make docs
-      - name: Deploy
-        uses: peaceiris/actions-gh-pages@v4
+      - uses: actions-ext/yardang@main
         with:
-          publish_branch: gh-pages
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/html
-          force_orphan: true
+          token: ${{ secrets.GITHUB_TOKEN }}

docs/src/configuration.md

@@ -113,24 +113,30 @@ Whether or not to use [Sphinx AutoAPI](https://sphinx-autoapi.readthedocs.io/en/
 use-autoapi = true
 ```
 
-## [Autodoc Pydantic](https://autodoc-pydantic.readthedocs.io/en/stable/users/examples.html) arguments
+## Sphinx Options
 
-[Configuration for Autodoc Pydantic](https://autodoc-pydantic.readthedocs.io/en/stable/users/configuration.html).
+```toml
+[tool.yardang]
+html_theme_options = {}
+html_static_path = []
+html_css_files = []
+html_js_files = []
+source_suffix = []
+exclude_patterns = []
+language = "en"
+pygments_style = "sphinx"
+```
+
+
+## [Myst](https://myst-parser.readthedocs.io/en/latest/#)
 
 ```toml
 [tool.yardang]
-autodoc_pydantic_model_show_config_summary = false
-autodoc_pydantic_model_show_validator_summary = false
-autodoc_pydantic_model_show_validator_members = false
-autodoc_pydantic_field_list_validators = false
-autodoc_pydantic_field_show_constraints = false
-autodoc_pydantic_model_member_order = "bysource"
-autodoc_pydantic_model_show_json = true
-autodoc_pydantic_settings_show_json = false
-autodoc_pydantic_model_show_field_summary = false
+myst_enable_extensions = ["colon_fence"]
+myst_fence_as_directive = ["mermaid"]
 ```
 
-## Myst-NB
+## [Myst-NB](https://myst-nb.readthedocs.io/en/latest/#)
 
 ```toml
 [tool.yardang]
@@ -158,6 +164,22 @@ An example follows:
   ../notebooks/example
 ```
 
+## [Autodoc Pydantic](https://autodoc-pydantic.readthedocs.io/en/stable/users/examples.html) arguments
+
+[Configuration for Autodoc Pydantic](https://autodoc-pydantic.readthedocs.io/en/stable/users/configuration.html).
+
+```toml
+[tool.yardang]
+autodoc_pydantic_model_show_config_summary = false
+autodoc_pydantic_model_show_validator_summary = false
+autodoc_pydantic_model_show_validator_members = false
+autodoc_pydantic_field_list_validators = false
+autodoc_pydantic_field_show_constraints = false
+autodoc_pydantic_model_member_order = "bysource"
+autodoc_pydantic_model_show_json = true
+autodoc_pydantic_settings_show_json = false
+autodoc_pydantic_model_show_field_summary = false
+```
 
 ## Mermaid
 
@@ -207,3 +229,23 @@ graph TD
   Z(Pay vendor invoice) --->R
   AA([Finish])
 ```
+
+## GitHub Admonitions
+
+GitHub admonitions are automatically translated to sphinx.
+
+> [!NOTE]
+> Note content
+
+> [!TIP]
+> Tip content
+
+> [!IMPORTANT]
+> Important content
+
+> [!WARNING]
+> Warning content
+
+> [!CAUTION]
+> Caution content
+

docs/src/overview.md

@@ -33,25 +33,17 @@ The following yaml should be all it takes to integrate your project with GitHub
 name: Docs
 on:
   push:
-    branches:
-      - main
+    branches: ["main"]
+    tags: ["v*"]
+    paths-ignore: ["LICENSE", "README.md"]
 permissions:
-  contents: write
+    contents: write
 jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions-ext/yardang@main
         with:
-          python-version: 3.11
-      - run: pip install .
-      - run: pip install yardang
-      - run: yardang build
-      - name: Deploy
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          publish_branch: gh-pages
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/html
+        token: ${{ secrets.GITHUB_TOKEN }}
+
 ```

pyproject.toml

@@ -8,7 +8,7 @@ authors = [{name = "the yardang authors", email = "[email protected]"}]
 description="Easily generate sphinx documentation"
 readme = "README.md"
 license = { text = "Apache-2.0" }
-version = "0.1.5"
+version = "0.1.8"
 requires-python = ">=3.9"
 keywords = []
 
@@ -60,7 +60,7 @@ develop = [
 yardang = "yardang.cli:main"
 
 [tool.bumpversion]
-current_version = "0.1.5"
+current_version = "0.1.8"
 commit = true
 tag = false
 
@@ -123,6 +123,9 @@ testpaths = "yardang/tests"
 [tool.ruff]
 line-length = 150
 
+[tool.ruff.lint]
+extend-select = ["I"]
+
 [tool.ruff.lint.isort]
 combine-as-imports = true
 default-section = "third-party"
@@ -141,3 +144,31 @@ pages = [
     "docs/src/configuration.md",
 ]
 use-autoapi = true
+
+# Below are defaults, just to ensure working
+# sphinx
+html_theme_options = {"switcher" = { "json_url" = "https://mysite.org/en/latest/_static/switcher.json"}}
+html_static_path = ["test"]
+html_css_files = []
+html_js_files = []
+source_suffix = []
+exclude_patterns = []
+language = "en"
+pygments_style = "sphinx"
+
+# myst/myst-nb
+myst_enable_extensions = ["colon_fence"]
+myst_fence_as_directive = ["mermaid"]
+nb_execution_mode = "off"
+nb_execution_excludepatterns = []
+
+# autodoc/autodoc-pydantic
+autodoc_pydantic_model_show_config_summary = false
+autodoc_pydantic_model_show_validator_summary = false
+autodoc_pydantic_model_show_validator_members = false
+autodoc_pydantic_field_list_validators = false
+autodoc_pydantic_field_show_constraints = false
+autodoc_pydantic_model_member_order = "bysource"
+autodoc_pydantic_model_show_json = true
+autodoc_pydantic_settings_show_json = false
+autodoc_pydantic_model_show_field_summary = false

yardang/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.5"
+__version__ = "0.1.8"

yardang/build.py

@@ -1,9 +1,11 @@
 import os.path
 from contextlib import contextmanager
-from jinja2 import Environment, FileSystemLoader
 from pathlib import Path
 from tempfile import TemporaryDirectory
 from typing import List, Optional
+
+from jinja2 import Environment, FileSystemLoader
+
 from .utils import get_config
 
 __all__ = ("generate_docs_configuration",)
@@ -70,31 +72,33 @@ def generate_docs_configuration(
         source_dir = os.path.curdir
 
         configuration_args = {}
-        for f in (
-            # autodoc/autodoc-pydantic
-            "autodoc_pydantic_model_show_config_summary",
-            "autodoc_pydantic_model_show_validator_summary",
-            "autodoc_pydantic_model_show_validator_members",
-            "autodoc_pydantic_field_list_validators",
-            "autodoc_pydantic_field_show_constraints",
-            "autodoc_pydantic_model_member_order",
-            "autodoc_pydantic_model_show_json",
-            "autodoc_pydantic_settings_show_json",
-            "autodoc_pydantic_model_show_field_summary",
+        for config_option, default in {
+            # sphinx generic
+            "html_theme_options": {},
+            "html_static_path": [],
+            "html_css_files": [],
+            "html_js_files": [],
+            "source_suffix": [],
+            "exclude_patterns": [],
+            "language": "en",
+            "pygments_style": "sphinx",
             # myst/myst-nb
-            "nb_execution_mode",
-            "nb_execution_excludepatterns",
-        ):
-            default_value = {
-                # autodoc/autodoc-pydantic
-                "autodoc_pydantic_model_member_order": '"bysource"',
-                "autodoc_pydantic_model_show_json": True,
-                # myst/myst-nb
-                "nb_execution_excludepatterns": [],
-                "nb_execution_mode": "off",
-            }.get(f, False)
-            config_value = get_config(section=f"{f}")
-            configuration_args[f] = default_value if config_value is None else config_value
+            "myst_enable_extensions": ["colon_fence"],
+            "myst_fence_as_directive": ["mermaid"],
+            "nb_execution_mode": "off",
+            "nb_execution_excludepatterns": [],
+            # autodoc/autodoc-pydantic
+            "autodoc_pydantic_model_show_config_summary": None,
+            "autodoc_pydantic_model_show_validator_summary": None,
+            "autodoc_pydantic_model_show_validator_members": None,
+            "autodoc_pydantic_field_list_validators": None,
+            "autodoc_pydantic_field_show_constraints": None,
+            "autodoc_pydantic_model_member_order": "bysource",
+            "autodoc_pydantic_model_show_json": True,
+            "autodoc_pydantic_settings_show_json": None,
+            "autodoc_pydantic_model_show_field_summary": None,
+        }.items():
+            configuration_args[config_option] = get_config(section=config_option) or default
         # create a temporary directory to store the conf.py file in
         with TemporaryDirectory() as td:
             templateEnv = Environment(loader=FileSystemLoader(searchpath=str(Path(__file__).parent.resolve())))

yardang/cli.py

@@ -1,13 +1,52 @@
-from sys import executable, stderr, stdout
+from pathlib import Path
 from subprocess import Popen
+from sys import executable, stderr, stdout
 from time import sleep
-from typer import Typer
+from typing import List, Optional
+
+from typer import Exit, Typer
 
 from .build import generate_docs_configuration
 
 
-def build(quiet: bool = False, debug: bool = False):
-    with generate_docs_configuration() as file:
+def build(
+    *,
+    quiet: bool = False,
+    debug: bool = False,
+    pdb: bool = False,
+    project: str = "",
+    title: str = "",
+    module: str = "",
+    description: str = "",
+    author: str = "",
+    copyright: str = "",
+    version: str = "",
+    theme: str = "furo",
+    docs_root: str = "",
+    root: str = "",
+    cname: str = "",
+    pages: Optional[List[Path]] = None,
+    use_autoapi: Optional[bool] = None,
+    custom_css: Optional[Path] = None,
+    custom_js: Optional[Path] = None,
+):
+    with generate_docs_configuration(
+        project=project,
+        title=title,
+        module=module,
+        description=description,
+        author=author,
+        copyright=copyright,
+        version=version,
+        theme=theme,
+        docs_root=docs_root,
+        root=root,
+        cname=cname,
+        pages=pages,
+        use_autoapi=use_autoapi,
+        custom_css=custom_css,
+        custom_js=custom_js,
+    ) as file:
         build_cmd = [
             executable,
             "-m",
@@ -26,6 +65,12 @@ def build(quiet: bool = False, debug: bool = False):
             process = Popen(build_cmd, stderr=stderr, stdout=stdout)
         while process.poll() is None:
             sleep(0.1)
+        if process.returncode != 0:
+            if pdb:
+                import pdb
+
+                pdb.set_trace()
+            raise Exit(process.returncode)
 
 
 def debug():