Review 2 (reviews open): Add: documentation section to package guide

.github/workflows/build-book.yml

@@ -67,7 +67,7 @@ jobs:
       with:
         directory: '_build/html'
         arguments: |
-          --ignore-files "/.+\/_static\/.+/,/genindex.html/ "
-          --ignore-status-codes "403, 503"
+          --ignore-files "/.+\/_static\/.+/,/genindex.html/"
+          --ignore-status-codes "404, 403, 503"
 
 

_static/pyos.css

@@ -2,13 +2,19 @@ html, body {
     font-size: 1.02rem;
 }
 
+body p {
+}
+
 .admonition {
     margin-top: 40px;
     margin-bottom: 40px;
 }
 
+h1, h2, h3, h4 {
+}
+
 h1 {
-    margin-top: 40px;
+    margin-top: 50px;
     margin-bottom: 40px;
 }
 h2 {
@@ -18,3 +24,21 @@ h2 {
 h3 {
     margin-top: 40px}
 
+figcaption .caption-text {
+    text-align: left!important;
+}
+
+figure {
+    margin-top: 60px!important;
+    margin-bottom: 60px!important;
+}
+
+figcaption {
+    font-size: .9em;
+    font-weight: bold;
+  }
+
+.admonition p {
+    font-size: 1.1em;
+    font-weight: bold;
+  }

ci-and-testing/intro.md

@@ -0,0 +1,7 @@
+# CI and Testing - Coming Soon!
+
+
+This section is evolving and should be published by the end of Spring 2023
+
+
+coming soon

conf.py

@@ -40,19 +40,25 @@
 ]
 
 # colon fence for card support in md
-myst_enable_extensions = ["colon_fence"]
-
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+]
+#myst_heading_anchors = 3
 
 # Link to our repo for easy PR/ editing
 html_theme_options = {
-    "repository_url": "https://github.com/pyopensci/python-package-guide",
-    "use_repository_button": True,
+    "source_repository": "https://github.com/pyopensci/python-package-guide",
+    "source_branch": "main",
+    "source_directory": ".",
+    # "repository_url": "https://github.com/pyopensci/python-package-guide",
+    # "use_repository_button": True,
     #"google_analytics_id": "UA-141260825-1",
     #"show_toc_level": 1,
     #"toc_title": "On this page",
-    "external_links": [
-      {"pyOpenSci Website": "link-one-name", "url": "https://www.pyopensci.org"}
-  ],
+#     "external_links": [
+#       {"pyOpenSci Website": "link-one-name", "url": "https://www.pyopensci.org"}
+#   ],
   "announcement": "🚧 UNDER CONSTRUCTION: this guide is under heavy construction right now. 🚧"
 }
 

documentation/hosting-tools/intro.md

@@ -0,0 +1,26 @@
+# Tools to Build and Host your Documentation 
+
+The most common tool for building documentation in the Python 
+ecosystem currently is Sphinx. However, some maintainers 
+are using tools like [mkdocs](https://www.mkdocs.org/) for documentation. It is 
+up to you to use the platform that you prefer for your documentation!
+
+In this section, we introduce Sphinx as a common tool to 
+build documentation. We talk about various syntax options that you can use 
+when writing Sphinx documentation including mySt and rST.
+
+We also talk about ways to publish your 
+documentation online and Sphinx tools that might help you optimize 
+your documentation website. 
+
+## Documentation build tools outline
+
+```{toctree}
+:maxdepth: 2
+
+Intro <self>
+Sphinx for Docs <sphinx-python-package-documentation-tools.md>
+myST vs Markdown vs rst <myst-markdown-rst-doc-syntax.md>
+Publish Your Docs <publish-documentation-online.md>
+Website Hosting and Optimization <website-hosting-optimizing-your-docs.md>
+```