Merge pull request #30 from python-project-templates/tkp/upd

Expose more options to end user, expose options via cli, fixes #15

Author: timkpaine

.github/workflows/docs.yml

@@ -1,30 +1,13 @@
 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
-        with:
-          publish_branch: gh-pages
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/html
-          force_orphan: true
+      - uses: actions-ext/yardang@main

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
+
+```toml
+[tool.yardang]
+html_theme_options = {}
+html_static_path = []
+html_css_files = []
+html_js_files = []
+source_suffix = []
+exclude_patterns = []
+language = "en"
+pygments_style = "sphinx"
+```
 
-[Configuration for Autodoc Pydantic](https://autodoc-pydantic.readthedocs.io/en/stable/users/configuration.html).
+
+## [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
 

docs/src/overview.md

@@ -33,25 +33,14 @@ 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
-        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
+      - uses: actions-ext/yardang@main
 ```

pyproject.toml

@@ -144,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/build.py

@@ -72,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,14 +1,52 @@
+from pathlib import Path
 from subprocess import Popen
 from sys import executable, stderr, stdout
 from time import sleep
+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",
@@ -28,6 +66,10 @@ def build(quiet: bool = False, debug: bool = False):
         while process.poll() is None:
             sleep(0.1)
         if process.returncode != 0:
+            if pdb:
+                import pdb
+
+                pdb.set_trace()
             raise Exit(process.returncode)
 
 

yardang/conf.py.j2

@@ -55,25 +55,27 @@ else:
 
 os.environ["SPHINX_BUILDING"] = "1"
 html_theme = "{{theme}}"
-html_theme_options = {}
-html_static_path = []
+html_theme_options = {{html_theme_options}}
+html_static_path = {{html_static_path}}
 html_css_files = [
     "styles/custom.css",
+    *{{html_css_files}},
 ]
 html_js_files = [
     "js/custom.js",
+    *{{html_js_files}}
 ]
 
 master_doc = "index"
 templates_path = ["_templates"]
-source_suffix = [".rst", ".md"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "node_modules", "_skbuild", ".pytest_cache", "js/*"]
-language = "en"
-pygments_style = "sphinx"
+source_suffix = [".rst", ".md", *{{source_suffix}}]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "node_modules", "_skbuild", ".pytest_cache", "js/*", *{{exclude_patterns}}]
+language = "{{language}}"
+pygments_style = "{{pygments_style}}"
 
 # myst / myst-nb
-myst_enable_extensions = ["colon_fence"]
-myst_fence_as_directive = ["mermaid"]
+myst_enable_extensions = {{myst_enable_extensions}}
+myst_fence_as_directive = {{myst_fence_as_directive}}
 nb_execution_mode = "{{nb_execution_mode}}"
 nb_execution_excludepatterns = {{nb_execution_excludepatterns}}
 
@@ -92,7 +94,7 @@ autodoc_pydantic_model_show_validator_summary = {{autodoc_pydantic_model_show_va
 autodoc_pydantic_model_show_validator_members = {{autodoc_pydantic_model_show_validator_members}}  # noqa: F821
 autodoc_pydantic_field_list_validators = {{autodoc_pydantic_field_list_validators}}  # noqa: F821
 autodoc_pydantic_field_show_constraints = {{autodoc_pydantic_field_show_constraints}}  # noqa: F821
-autodoc_pydantic_model_member_order = {{autodoc_pydantic_model_member_order}}  # noqa: F821
+autodoc_pydantic_model_member_order = "{{autodoc_pydantic_model_member_order}}"  # noqa: F821
 autodoc_pydantic_model_show_json = {{autodoc_pydantic_model_show_json}}  # noqa: F821
 autodoc_pydantic_settings_show_json = {{autodoc_pydantic_settings_show_json}}  # noqa: F821