Fix: Major reorganization following comments from @sneakers-the-rat

Author: lwasser

ci-and-testing/intro.md

@@ -0,0 +1,3 @@
+# CI and Testing 
+
+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/contributing-license-coc.md

@@ -0,0 +1,19 @@
+# Tools to Build and Host your Documentation 
+
+The mmostsot common tool for building documentation in the Python 
+ecosystem is Sphinx. However, some are using tools like 
+mkdocs for documentation. In the end 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 also talk about ways to publish your 
+documentation online and Sphinx tools that might help you optimize 
+your documentation website. 
+
+```{toctree}
+:maxdepth: 2
+
+Sphinx Tools <python-package-documentation-tools.md>
+Publish Your Docs <publish-documentation-online.md>
+Website Hosting and Optimization <website-hosting-optimizing-your-docs.md>
+```

documentation/hosting-tools/intro.md

@@ -0,0 +1,16 @@
+# How to publish your Python package documentation online
+
+We suggest that you setup a hosting service for your Python package 
+documentation. Two free and commonly used ways to
+quickly create a documentation website hosting environment are below. 
+
+1. You can host your documentation yourself using [GitHub Pages](https://pages.github.com/) or another online hosting service. 
+1. You can host your documentation using [Read the Docs](https://readthedocs.org/).
+
+If you don't want to maintain a documentation website for your Python package, 
+we suggest using the Read the Docs website. Read the Docs allows you to:
+
+* Quickly launch a website using the documentation found in your GitHub repository.  
+* Track versions of your documentation as you release updates.
+* Provides support for Google analytics.
+* Allows you to turn on integration with pull requests where you can view documentation build progress (success vs failure).

documentation/hosting-tools/publish-documentation-online.md

@@ -0,0 +1,109 @@
+# Python Package Documentation
+
+<!-- TODO: make this into include files so we can have a summary 
+important points page -->
+
+```{important}
+
+## Take Aways: Key Python Package Tools to Use
+
+* Use Sphinx to build your documentation
+* Publish your documentation on ReadTheDocs (or GitHub pages if you are more advanced and also prefer to maintain your website locally)
+* Use `myST` syntax to write your documentation 
+* Use sphinx gallery to write tutorials using .py files that automagically have downloadable .py and jupyter notebook files. Use nbsphinx if you prefer writing tutorials in jupyter notebook format and don't need a grid formatted gallery. *Both of these tools will run your tutorials from beginning to end providing an addition layer of testing to your package!*
+* OPTIONAL: Use [doctest](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html) to run the examples in your code's docstrings as a way to make sure that your code's functions and methods (the API) are running as you expect them to. 
+```
+
+In addition to your:
+* [README.md file](readme-file-best-practices), 
+* [CONTRIBUTING.md and development guides and LICENSE file](contributing-license-coc),
+
+you should also have user-facing documentation for your Python 
+package. Most often, user-facing documentation is contained on a hosted 
+website. 
+
+Below you will learn about the most common tools that 
+are used to build scientific Python packaging documentation. You will also 
+learn about hosting options for your documentation. 
+
+Here, we focus on tools and infrastructure that you can use. 
+[Click here if you want to learn more about documentation best practices](package-documentation-best-practices.md).
+
+```{note}
+Examples of documentation websites that we love:
+
+* [GeoPandas](https://geopandas.org/en/stable/)
+    * [View rst to create landing page](https://raw.githubusercontent.com/geopandas/geopandas/main/doc/source/index.rst)
+* [verde](https://www.fatiando.org/verde/latest/)
+    * [View verde landing page code - rst file.](https://github.com/fatiando/verde/blob/main/doc/index.rst)
+* [Here is our documentation if you want to see a myST example of a landing page.](https://github.com/pyOpenSci/python-package-guide/blob/main/index.md)
+```
+
+
+## Sphinx, the most common tool used in the scientific Python ecosystem 
+
+Most scientific Python packages use [sphinx](https://www.sphinx-doc.org/) to 
+build their documentation. As such, we will focus on sphinx in this guide. 
+
+Sphinx is a [static-site generator](https://www.cloudflare.com/learning/performance/static-site-generator/). A static site generator is a tool that creates 
+html for a website based upon a set of templates. Sphinx is written 
+using Python tool which 
+is why it's commonly used in the Python ecosystem. 
+
+```{tip} 
+There are other static site generator tools that could be used to create user-facing documentation including 
+ [mkdocs](https://www.mkdocs.org/). We won't 
+discuss others tools in this guide given sphinx is currently the most 
+popular in the scientific Python ecosystem. 
+
+You are welcome to use whatever documentation tool that you prefer for your Python package development! 
+```
+
+### Sphinx sites can be optimized for documentation with extensions and themes 
+
+The functionality of sphinx can be extended using extensions and themes. A few 
+examples include:
+
+* You can apply documentation themes for quick generation of beautiful documentation.
+* You can [automatically create documentation for your package's functions and classes (that package's API) from docstrings in your code using the autodoc extension](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html)
+* You can [run and test code examples in your docstrings using the doctest extension](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html)
+* While sphinx natively supports the `rST` syntax. You can add custom syntax parsers to support easier-to-write syntax using tools such as [myst](https://myst-parser.readthedocs.io/).
+
+You are free to use whatever sphinx theme that you prefer. However, the most 
+common sphinx themes that we recommend for the Python scientific 
+community include:  
+
+* [pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/) 
+* [sphinx-book-theme](https://sphinx-book-theme.readthedocs.io/)
+* [furo](https://pradyunsg.me/furo/quickstart/)
+
+
+```{tip}
+This book is created using sphinx and the `furo` theme.
+```
+
+## Documentation syntax: markdown vs. myST vs. rst syntax to create your docs 
+
+There are three commonly used syntaxes for creating Python documentation:
+1. [markdown](https://www.markdownguide.org/): Markdown is an easy-to-learn text 
+syntax. It is the default syntax use in Jupyter Notebooks. There are tools that you can add to a sphinx website that allow it to render markdown as html. However, using markdown to write documentation has limitations. For instance if you want to add references, 
+colored call out blocks and other custom elements to your documentation, you will 
+need to use either **myST** or **rST**.
+1. [rST (ReStructured Text):](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). **rST** is the native syntax that sphinx supports. rST was the default syntax used for documentation for many years given the limitations of markdown. However, in recent years myST has risen to the top as a favorite for documentation given the flexibility that it allows.
+1. [myST:](https://myst-parser.readthedocs.io/en/latest/intro.html) myST is a combination of vanilla of `markdown` and `rST` syntax. It is a nice option if you are comfortable writing markdown. `myst` is preferred by many because it offers both the rich functionality 
+of rST combined with a simple-to-write markdown syntax. 
+
+While you can chose to use any of the syntaxes listed above, we suggest using 
+`myST` because:
+
+* It is a simpler syntax and thus easier to learn;
+* The above simplicity will make it easier for more people to contribute to your documentation. 
+* Most of your core python package text files, such as your README.md file, are already in `.md` format
+* `GitHub` and `Jupyter Notebooks` support markdown thus it's more widely used in the scientific ecosystem. 
+
+
+```{tip}
+If you are on the fence about myST vs rst, you might find that **myST** is easier 
+for more people to contribute to.  
+```
+

documentation/hosting-tools/python-package-documentation-tools.md

@@ -1,31 +1,9 @@
-# Hosting your Python package documentation and optimizing online content 
-
-## How to host your Python package documentation
-
-We suggest that you setup a hosting service for your Python package 
-documentation. Two free and commonly used ways to
-quickly create a documentation website hosting environment are below. 
-
-1. You can host your documentation yourself using [GitHub Pages](https://pages.github.com/) or another online hosting service. 
-1. You can host your documentation using [Read the Docs](https://readthedocs.org/).
-
-If you don't want to maintain a documentation website for your Python package, 
-we suggest using the Read the Docs website. Read the Docs allows you to:
-
-* Quickly launch a website using the documentation found in your GitHub repository.  
-* Track versions of your documentation as you release updates.
-* Provides support for Google analytics.
-* Allows you to turn on integration with pull requests where you can view documentation build progress (success vs failure).
-
-
-
-## Optimizing your documentation so search engines (and other users) find it
+# Optimizing your documentation so search engines (and other users) find it
 
 If you are interested in more people finding your package, you may want to 
 add some core sphinx extensions (and theme settings) that will help search 
 engines such as Google find your documentation. 
 
-
 ### Google Analytics
 Some of the [sphinx themes such as the `pydata-sphinx-theme` and 
 sphinx-book-theme have built in support for google analytics](https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/analytics.html#google-analytics). However, if the theme that you chose does not offer 

documentation/website-hosting-optimizing-your-docs.md renamed to documentation/hosting-tools/website-hosting-optimizing-your-docs.md

@@ -1,5 +1,15 @@
 # Documentation for your Open Source Python Package: An Overview
 
+<!-- ```{toctree}
+:hidden:
+
+Best Practices for Docs <package-documentation-best-practices>
+Tools to Build Your Docs <python-package-documentation-tools>
+Host & Help People Find Your Docs <website-hosting-optimizing-your-docs>
+The README File <readme-file-best-practices.md>
+Contributing & License files <contributing-license-coc>
+``` -->
+
 ```{important}
 ## Quick Takeaways: Documentation must haves