docs(SPHINX): upgrade, reorganize, add rtd theme

osx-provisioner · Jan 17, 2024 · 8df8b7d · 8df8b7d
1 parent cbef0ce
commit 8df8b7d
Show file tree

Hide file tree

Showing 17 changed files with 530 additions and 383 deletions.
diff --git a/README.md b/README.md
@@ -79,17 +79,17 @@ You can work with `Profiles` in one of two ways:
 
 To find out more:
 
-- Read about the `Mac Maker Profiles`, and how to build one [here](https://mac-maker.readthedocs.io/en/latest/project/3.profiles.html).
+- Read about the `Mac Maker Profiles`, and how to build one [here](https://mac-maker.readthedocs.io/en/latest/project/4.profiles.html).
 - Use [this template](https://github.com/osx-provisioner/profile-generator) to create your own custom profiles.
-- Read about the `spec.json` file, and how to build one [here](https://mac-maker.readthedocs.io/en/latest/project/4.spec_files.html).
+- Read about the `spec.json` file, and how to build one [here](https://mac-maker.readthedocs.io/en/latest/project/5.spec_files.html).
 
 **Please Note:**
 - We've had some user feedback that the `spec.json` files are a bit complicated to get started with.
 - Although we'll continue to support them, we'll soon introduce the ability to simply specify the path to a `Mac Maker Profile` folder on the local filesystem.
 
 ## License
 
-As this project effectively bundles Ansible, it must comply with the [GNU GPL](https://mac-maker.readthedocs.io/en/latest/project/6.license.html).
+As this project effectively bundles Ansible, it must comply with the [GNU GPL](https://mac-maker.readthedocs.io/en/latest/project/7.license.html).
 You are however free to use and modify this source, as long as the license's terms are respected.
 
 (Pull requests are most welcome, as I sincerely hope this project can be of use to others.)

diff --git a/documentation/source/_static/css/overrides.css b/documentation/source/_static/css/overrides.css
@@ -0,0 +1,3 @@
+.wy-nav-content {
+    max-width: 100%;
+}
diff --git a/documentation/source/conf.py b/documentation/source/conf.py
@@ -7,6 +7,7 @@
 # -- Path setup --------------------------------------------------------------
 
 import os
+import pathlib
 import sys
 
 if os.path.exists('/app'):
@@ -29,14 +30,15 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
-    'sphinx_autopackagesummary',
     'sphinx_autodoc_typehints',
+    'sphinx_autopackagesummary',
     'sphinx_click.ext',
     'sphinx-jsonschema',
-    'sphinx.ext.intersphinx',
     'sphinxcontrib.spelling',
+    'myst_parser',
 ]
 
 # sphinx.ext.autosummary
@@ -53,21 +55,31 @@
 tokenizer_lang = 'en_US'
 spelling_word_list_filename = 'spelling_wordlist.txt'
 
-# sphinx_autopackagesummary
-autosummary_generate = True
-autosummary_mock_imports = [
-    "mac_maker.tests",
-    "mac_maker.ansible_controller.tests",
-    "mac_maker.jobs.tests",
-    "mac_maker.utilities.tests",
-    "mac_maker.utilities.mixins.tests",
-    "mac_maker.utilities.validation.tests",
-]
+
+def detect_tests():
+  """Create a list of import paths with tests."""
+
+  test_paths = []
+  for root, dirs, _ in os.walk('../../pi_portal'):
+    for name in dirs:
+      if name == 'tests':
+        directory = pathlib.Path(os.path.join(root, name).replace('../../', ''))
+        test_paths.append('.'.join(directory.with_suffix('').parts))
+  return test_paths
+
+
+# Exclude tests from sphinx_autopackagesummary here
+autosummary_mock_imports = detect_tests()
 
 source_suffix = {
     '.rst': 'restructuredtext',
 }
 
+typehints_fully_qualified = False
+always_document_param_types = True
+typehints_defaults = "comma"
+typehints_document_rtype = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -81,12 +93,12 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'haiku'
+html_theme = 'sphinx_rtd_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-#html_static_path = ['_static']
-html_theme_options = {
-    'body_max_width': '100%'
-}
+html_static_path = ['_static']
+html_css_files = [
+    'css/overrides.css',
+]
diff --git a/documentation/source/project/0.overview.md b/documentation/source/project/0.overview.md
@@ -0,0 +1,7 @@
+Project Overview
+================
+```{include} ../../../README.md
+:start-after: Project Documentation
+:end-before: License
+```
+
diff --git a/documentation/source/project/0.python.rst → documentation/source/project/1.python.rst b/documentation/source/project/0.python.rst → documentation/source/project/1.python.rst
diff --git a/documentation/source/project/2.cli.rst b/documentation/source/project/2.cli.rst
diff --git a/documentation/source/project/1.usage.rst → documentation/source/project/2.usage.rst b/documentation/source/project/1.usage.rst → documentation/source/project/2.usage.rst
diff --git a/documentation/source/project/3.cli.rst b/documentation/source/project/3.cli.rst
@@ -0,0 +1,6 @@
+CLI Summary
+===========
+
+.. click:: mac_maker.cli:cli
+    :prog: mac_maker.cli
+    :nested: short
diff --git a/documentation/source/project/3.cli_reference.rst b/documentation/source/project/3.cli_reference.rst
@@ -0,0 +1,6 @@
+CLI Subcommand Reference
+========================
+
+.. click:: mac_maker.cli:cli
+    :prog: mac_maker.cli
+    :nested: full
diff --git a/documentation/source/project/3.profiles.rst → documentation/source/project/4.profiles.rst b/documentation/source/project/3.profiles.rst → documentation/source/project/4.profiles.rst
diff --git a/...mentation/source/project/4.spec_files.rst → ...mentation/source/project/5.spec_files.rst b/...mentation/source/project/4.spec_files.rst → ...mentation/source/project/5.spec_files.rst
diff --git a/documentation/source/project/5.build.rst → documentation/source/project/6.build.rst b/documentation/source/project/5.build.rst → documentation/source/project/6.build.rst
diff --git a/documentation/source/project/6.license.rst → documentation/source/project/7.license.rst b/documentation/source/project/6.license.rst → documentation/source/project/7.license.rst
diff --git a/documentation/source/project/7.readme.rst b/documentation/source/project/7.readme.rst
diff --git a/documentation/source/spelling_wordlist.txt b/documentation/source/spelling_wordlist.txt
@@ -1,5 +1,7 @@
 ansible
+bitrise
 codebase
+cmd
 env
 filesystem
 github
@@ -9,8 +11,10 @@ localhost
 mac_maker
 minItems
 mixin
+pre
 precheck
 repo
+subcommand
 sudo
 uniqueItems
 url