Add source-code flag to builds. (#13)

Author: kattni

.pyspelling.yml

@@ -33,3 +33,6 @@ matrix:
         - open: '{%'
           content: '[\d\D]*'
           close: '%}'
+        - open: ':::'
+          content: '[\d\D]*'
+          close: '\n'

docs/config.yml

@@ -76,3 +76,8 @@ plugins:
   literate-nav:
     nav_file: SUMMARY.md
   macros: {}
+  mkdocstrings:
+    default_handler: python
+    handlers:
+      python:
+        paths: [src]

docs/en/section_one/page_two.md

@@ -6,3 +6,12 @@ Navigation should render at the bottom of the page; "BeeWare Docs Tools Demo
 Section One" should be on the left, "Section Two" should be on the right.
 The footer should be below the navigation links. This confirms the theme
 configuration has been applied.
+
+### Class reference documentation
+
+The following should show the reference documentation for the `DocsTest`
+class, located in `docs_test.py`, in the `src/beeware_docs_tools`
+directory. This verifies that the source code directory symlinking is
+working properly.
+
+::: beeware_docs_tools.docs_test.DocsTest

docs/spelling_wordlist

@@ -12,6 +12,7 @@ reStructuredText
 subdirectories
 subdirectory
 symlinked
+symlinking
 Titlebar
 titlebar
 Weblate

pyproject.toml

@@ -30,6 +30,7 @@ dependencies = [
     "mkdocs-macros-plugin==1.3.9",
     "mkdocs-material==9.6.17",
     "mkdocs==1.6.1",
+    "mkdocstrings-python==1.16.12",
     "pymdown-extensions==10.16.1",
     "pyspelling==2.10",
     "python-Levenshtein==0.27.1",

src/beeware_docs_tools/build_md_translations.py

@@ -16,6 +16,7 @@ def parse_args() -> Namespace:
     parser.add_argument("language_code", nargs="*")
     parser.add_argument("--output", default=SOURCE_DIR / "_build" / "html")
     parser.add_argument("--build-with-errors", action="store_true")
+    parser.add_argument("--source-code", action="append")
     args = parser.parse_args()
     for language_code in args.language_code:
         if not (
@@ -87,6 +88,17 @@ def main():
         ) as config_temp:
             yaml.dump(config_file, config_temp)
 
+        # If source code directory or directories provided, symlink.
+        if args.source_code:
+            for directory in args.source_code:
+                if "/" in directory:
+                    Path(temp_md_directory / directory).parent.mkdir(
+                        parents=True, exist_ok=True
+                    )
+                (temp_md_directory / directory).symlink_to(
+                    SOURCE_DIR / directory, target_is_directory=True
+                )
+
         # Symlink overrides directory to the temp directory, so it is
         # available relative to the build.
         (temp_md_directory / "overrides").symlink_to(

src/beeware_docs_tools/docs_test.py

@@ -0,0 +1,8 @@
+class DocsTest:
+    def __init__(self):
+        """This is the test class."""
+        pass
+
+    def attribute(self):
+        """This is a test attribute."""
+        pass

src/beeware_docs_tools/live_serve_en.py

@@ -19,6 +19,7 @@ def parse_args() -> Namespace:
     parser = ArgumentParser()
     parser.add_argument("watch_directory", nargs="*")
     parser.add_argument("--build-with-errors", action="store_true")
+    parser.add_argument("--source-code", action="append")
     args = parser.parse_args()
 
     return args
@@ -53,9 +54,21 @@ def serve_docs(config_location) -> None:
 
 
 def main():
+    args = parse_args()
+
     with TemporaryDirectory() as temp_md_directory:
         temp_md_directory = Path(temp_md_directory)
 
+        if args.source_code:
+            for directory in args.source_code:
+                if "/" in directory:
+                    Path(temp_md_directory / directory).parent.mkdir(
+                        parents=True, exist_ok=True
+                    )
+                (temp_md_directory / directory).symlink_to(
+                    SOURCE_DIR / directory, target_is_directory=True
+                )
+
         config_file = yaml.load(
             open(SOURCE_DIR / "docs" / "config.yml"), Loader=yaml.SafeLoader
         )

tox.ini

@@ -14,13 +14,13 @@ skip_install = true
 deps =
     -r {tox_root}/requirements.docs.txt
 commands:
-    !lint-!all-!translate-!live-!en-!fr-!de : build_md_translations {posargs} en
+    !lint-!all-!translate-!live-!en-!fr-!de : build_md_translations {posargs} --source-code=src en
     translate : md2po --input docs{/}en --output {[docs]templates_dir} --pot --duplicates=merge
     translate : build_po_translations fr de
     lint : markdown-checker --dir {[docs]docs_dir} --func check_broken_urls
     lint : pyspelling
-    live : live_serve_en {posargs} src
-    all : build_md_translations {posargs} en fr de
-    en : build_md_translations {posargs} en
-    fr : build_md_translations {posargs} fr
-    de : build_md_translations {posargs} de
+    live : live_serve_en {posargs} src --source-code=src
+    all : build_md_translations {posargs} --source-code=src en fr de
+    en : build_md_translations {posargs} --source-code=src en
+    fr : build_md_translations {posargs} --source-code=src fr
+    de : build_md_translations {posargs} --source-code=src de