Merge pull request #172 from blink1073/docs-improvements

Steven Silvester · web-flow · commit 95b9a11ffb04 · 2021-09-30T07:52:51.000-05:00
Add generated docs and logos
diff --git a/docs/environment.yml b/docs/environment.yml
@@ -9,3 +9,5 @@ dependencies:
   - myst-parser
   - pip:
       - pydata_sphinx_theme
+      - numpydoc
+      - sphinx-click
diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css
@@ -0,0 +1,4 @@
+/* Added to avoid logo being too squeezed */
+.navbar-brand {
+  height: 4rem !important;
+}
diff --git a/docs/source/_static/images/logo/favicon.svg b/docs/source/_static/images/logo/favicon.svg
@@ -0,0 +1,6 @@
+<svg width="152" height="165" viewBox="0 0 152 165" version="1.1" xmlns="http://www.w3.org/2000/svg">
+  <g class="jp-icon-warn0" fill="#F37726">
+    <path transform="translate(0.078947, 110.582927)" d="M75.9422842,29.5804561 C43.3023947,29.5804561 14.7967832,17.6534634 0,0 C5.51083211,15.8406829 15.7815389,29.5667732 29.3904947,39.2784171 C42.9997,48.9898537 59.2737,54.2067805 75.9605789,54.2067805 C92.6474579,54.2067805 108.921458,48.9898537 122.530663,39.2784171 C136.139453,29.5667732 146.410284,15.8406829 151.921158,0 C137.087868,17.6534634 108.582589,29.5804561 75.9422842,29.5804561 L75.9422842,29.5804561 Z" />
+    <path transform="translate(0.037368, 0.704878)" d="M75.9784579,24.6264073 C108.618763,24.6264073 137.124458,36.5534415 151.921158,54.2067805 C146.410284,38.366222 136.139453,24.6401317 122.530663,14.9284878 C108.921458,5.2168439 92.6474579,0 75.9605789,0 C59.2737,0 42.9997,5.2168439 29.3904947,14.9284878 C15.7815389,24.6401317 5.51083211,38.366222 0,54.2067805 C14.8330816,36.5899293 43.3385684,24.6264073 75.9784579,24.6264073 L75.9784579,24.6264073 Z" />
+  </g>
+</svg>
diff --git a/docs/source/_static/images/logo/logo.svg b/docs/source/_static/images/logo/logo.svg
@@ -0,0 +1,13 @@
+<svg width="39" height="51" viewBox="0 0 39 51" xmlns="http://www.w3.org/2000/svg">
+  <g transform="translate(-1638 -2281)">
+    <g class="jp-icon-warn0" fill="#F37726">
+      <path transform="translate(1639.74 2311.98)" d="M 18.2646 7.13411C 10.4145 7.13411 3.55872 4.2576 0 0C 1.32539 3.8204 3.79556 7.13081 7.0686 9.47303C 10.3417 11.8152 14.2557 13.0734 18.269 13.0734C 22.2823 13.0734 26.1963 11.8152 29.4694 9.47303C 32.7424 7.13081 35.2126 3.8204 36.538 0C 32.9705 4.2576 26.1148 7.13411 18.2646 7.13411Z"/>
+      <path transform="translate(1639.73 2285.48)" d="M 18.2733 5.93931C 26.1235 5.93931 32.9793 8.81583 36.538 13.0734C 35.2126 9.25303 32.7424 5.94262 29.4694 3.6004C 26.1963 1.25818 22.2823 0 18.269 0C 14.2557 0 10.3417 1.25818 7.0686 3.6004C 3.79556 5.94262 1.32539 9.25303 0 13.0734C 3.56745 8.82463 10.4232 5.93931 18.2733 5.93931Z"/>
+    </g>
+    <g class="jp-icon3" fill="#616161">
+      <path transform="translate(1669.3 2281.31)" d="M 5.89353 2.844C 5.91889 3.43165 5.77085 4.01367 5.46815 4.51645C 5.16545 5.01922 4.72168 5.42015 4.19299 5.66851C 3.6643 5.91688 3.07444 6.00151 2.49805 5.91171C 1.92166 5.8219 1.38463 5.5617 0.954898 5.16401C 0.52517 4.76633 0.222056 4.24903 0.0839037 3.67757C -0.0542483 3.10611 -0.02123 2.50617 0.178781 1.95364C 0.378793 1.4011 0.736809 0.920817 1.20754 0.573538C 1.67826 0.226259 2.24055 0.0275919 2.82326 0.00267229C 3.60389 -0.0307115 4.36573 0.249789 4.94142 0.782551C 5.51711 1.31531 5.85956 2.05676 5.89353 2.844Z"/>
+      <path transform="translate(1639.8 2323.81)" d="M 7.42789 3.58338C 7.46008 4.3243 7.27355 5.05819 6.89193 5.69213C 6.51031 6.32607 5.95075 6.83156 5.28411 7.1446C 4.61747 7.45763 3.87371 7.56414 3.14702 7.45063C 2.42032 7.33712 1.74336 7.0087 1.20184 6.50695C 0.660328 6.0052 0.27861 5.35268 0.105017 4.63202C -0.0685757 3.91135 -0.0262361 3.15494 0.226675 2.45856C 0.479587 1.76217 0.931697 1.15713 1.52576 0.720033C 2.11983 0.282935 2.82914 0.0334395 3.56389 0.00313344C 4.54667 -0.0374033 5.50529 0.316706 6.22961 0.987835C 6.95393 1.65896 7.38484 2.59235 7.42789 3.58338L 7.42789 3.58338Z"/>
+      <path transform="translate(1638.36 2286.06)" d="M 2.27471 4.39629C 1.84363 4.41508 1.41671 4.30445 1.04799 4.07843C 0.679268 3.8524 0.385328 3.52114 0.203371 3.12656C 0.0214136 2.73198 -0.0403798 2.29183 0.0258116 1.86181C 0.0920031 1.4318 0.283204 1.03126 0.575213 0.710883C 0.867222 0.39051 1.24691 0.164708 1.66622 0.0620592C 2.08553 -0.0405897 2.52561 -0.0154714 2.93076 0.134235C 3.33591 0.283941 3.68792 0.551505 3.94222 0.90306C 4.19652 1.25462 4.34169 1.67436 4.35935 2.10916C 4.38299 2.69107 4.17678 3.25869 3.78597 3.68746C 3.39516 4.11624 2.85166 4.37116 2.27471 4.39629L 2.27471 4.39629Z"/>
+    </g>
+  </g>>
+</svg>
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -32,7 +32,13 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["myst_parser"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "myst_parser",
+    "sphinx_click",
+]
 
 myst_enable_extensions = ["html_image"]
 
@@ -52,6 +58,9 @@
 #
 html_theme = "pydata_sphinx_theme"
 
+html_logo = "_static/images/logo/logo.svg"
+html_favicon = "_static/images/logo/favicon.svg"
+
 # 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".
@@ -74,3 +83,4 @@
 def setup(app):
     dest = osp.join(HERE, "reference", "changelog.md")
     shutil.copy(osp.join(HERE, "..", "..", "CHANGELOG.md"), dest)
+    app.add_css_file("custom.css")
diff --git a/docs/source/get_started/making_first_release.md b/docs/source/get_started/making_first_release.md
@@ -74,5 +74,7 @@ already uses Jupyter Releaser.
   ![Full Release Workflow Next Step](../images/publish_release_next_step.png)
 
 - **Note** If the publish portion fails you can attempt to publish the draft GitHub release given by the URL in the "\*\* Failure Message \*\*" using the "Publish Release" workflow.
+- **Note** GitHub Actions caches the secrets used on a given workflow run. So if you run into an auth issue, you'll
+  need to run a new workflow instead of re-running the existing workflow.
 - Review and merge the forward-port PR if applicable
 - Announce the release on appropriate channels
diff --git a/docs/source/how_to_guides/write_config.md b/docs/source/how_to_guides/write_config.md
@@ -27,7 +27,7 @@ Note: the only unusable hook names are `before-prep-git` and `before-extract-rel
 
 This is where `jupyter-releaser` looks for configuration (first one found is used):
 
-```code
+```
     .jupyter-releaser.toml
     pyproject.toml (in the tools.jupyter-releaser section )
     package.json (in the jupyter-releaser property)
diff --git a/docs/source/reference/api_docs.rst b/docs/source/reference/api_docs.rst
@@ -1,4 +1,30 @@
 API Docs
 ========
 
-Coming soon!
+Library Functions
+-----------------
+.. automodule:: jupyter_releaser.lib
+    :members:
+
+Python Utility Functions
+------------------------
+.. automodule:: jupyter_releaser.python
+    :members:
+
+
+NPM Utility Functions
+------------------------
+.. automodule:: jupyter_releaser.npm
+    :members:
+
+
+Changelog Utility Functions
+---------------------------
+.. automodule:: jupyter_releaser.changelog
+    :members:
+
+
+Global Utility Functions
+------------------------
+.. automodule:: jupyter_releaser.util
+    :members:
diff --git a/docs/source/reference/releaser_cli.md b/docs/source/reference/releaser_cli.md
diff --git a/docs/source/reference/releaser_cli.rst b/docs/source/reference/releaser_cli.rst
@@ -0,0 +1,6 @@
+Releaser CLI
+============
+
+.. click:: jupyter_releaser.cli:main
+  :prog: jupyter-releaser
+  :nested: full
