Fix: move book to pydata_sphinx_theme

Author: lwasser

_static/pyos.css

@@ -36,9 +36,9 @@ figure {
 figcaption {
     font-size: .9em;
     font-weight: bold;
-  }
+}
+
 
 .admonition p {
-    font-size: 1.1em;
-    font-weight: bold;
-  }
+    font-size: 1em;
+}

code-style-structure/intro.md

@@ -18,8 +18,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'python-package-guide'
-copyright = '2022, pyOpenSci'
-author = 'Leah Wasser'
+copyright = '2023, pyOpenSci'
+author = 'pyOpenSci Community'
 
 # The full version, including alpha/beta/rc tags
 release = '0.1'
@@ -44,22 +44,57 @@
     "colon_fence",
     "deflist",
 ]
-#myst_heading_anchors = 3
+myst_heading_anchors = 3
+
+# For generating sitemap
+html_baseurl = 'https://www.pyopensci.org/software-peer-review/'
 
 # Link to our repo for easy PR/ editing
 html_theme_options = {
-    "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"}
-#   ],
-  "announcement": "🚧 UNDER CONSTRUCTION: this guide is under heavy construction right now. 🚧"
+    "announcement": "🚧 This guide is currently under heavy construction 🚧 ",
+    "external_links": [
+        {
+            "url": "https://www.pyopensci.org",
+            "name": "pyOpenSci Website",
+        },
+        {
+            "url": "https://www.pyopensci.org/python-package-guide",
+            "name": "Python Packaging Guide",
+        },
+        {
+            "url": "https://pyopensci.org/governance",
+            "name": "Governance",
+        },
+    ],
+    "icon_links": [
+        {
+            "name": "Mastodon",
+            "url": "https://fosstodon.org/@pyOpenSci",
+            "icon": "fa-brands fa-mastodon",
+        },
+    ],
+    "logo": {
+        "text": "Python Package Guide",
+        "image_dark": "logo.png",
+        "alt_text": "pyOpenSci Python Package Guide. The pyOpenSci logo is blue and yellow following the Python logo",
+    },
+    "header_links_before_dropdown": 4,
+    "use_edit_page_button": True,
+    "show_toc_level": 1,
+    #"navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
+    "github_url": "https://github.com/pyopensci/python-package-guide",
+    "twitter_url": "https://twitter.com/pyopensci",
+    "footer_items": ["copyright"],
+}
+
+html_theme_options["analytics"] = {
+    "google_analytics_id": "UA-141260825-1",
+}
+
+html_context = {
+    "github_user": "pyopensci",
+    "github_repo": "python-package-guide",
+    "github_version": "main",
 }
 
 # Add analytics to furo theme
@@ -90,7 +125,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'furo'
+html_theme = 'pydata_sphinx_theme'
 html_static_path = ["_static"]
 html_css_files = ["pyos.css"]
 html_title = "pyOpenSci Package Guide"

conf.py

@@ -12,15 +12,3 @@ 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>
-```

documentation/hosting-tools/intro.md

@@ -4,9 +4,10 @@ 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
+## Google Analytics
 
 ```{important}
+
 Google analytics [is not compliant with the European General Data Protection Regulation (GDPR)](https://matomo.org/blog/2022/05/google-analytics-4-gdpr/). While there are many components to this regulation, one of the core elements is that you have to let users know on your site that you are collecting data and they have to consent. WHile it is possible to add infrastructure around Google Analytics to make it close to following GDPR regulations, the community is slowly shifting away from Google using open tools such as [Plausible](https://plausible.io/), [Cloudflare Web Analytics](https://www.cloudflare.com/web-analytics/) and [Matomo](https://matomo.org) for web analytics.
 
 pyOpenSci is currently looking into free options for open source

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

@@ -1,5 +1,49 @@
 # Documentation for your Open Source Python Package
 
+```{toctree}
+:hidden:
+:caption: Intro
+
+Documentation Overview <self>
+```
+
+```{toctree}
+:hidden:
+:maxdepth: 2
+:caption: Write User Documentation
+
+Intro <write-user-documentation/intro.md>
+Create Your Docs <write-user-documentation/get-started>
+Document Your Code (API) <write-user-documentation/document-your-code-api-docstrings.md>
+Create Package Tutorials <write-user-documentation/create-package-tutorials.md>
+```
+
+```{toctree}
+:hidden:
+:caption: Core Repository Files
+:maxdepth: 2
+
+Intro <repository-files/intro.md>
+README file <repository-files/readme-file-best-practices.md>
+Contributing File <repository-files/contributing-file.md>
+Code of Conduct File <repository-files/code-of-conduct-file.md>
+Development Guide <repository-files/development-guide.md>
+LICENSE files <repository-files/license-files.md>
+```
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: Documentation & Hosting Tools
+
+Intro <hosting-tools/intro>
+Sphinx for Docs <hosting-tools/sphinx-python-package-documentation-tools>
+myST vs Markdown vs rst <hosting-tools/myst-markdown-rst-doc-syntax>
+Publish Your Docs <hosting-tools/publish-documentation-online>
+Website Hosting and Optimization <hosting-tools/website-hosting-optimizing-your-docs>
+```
+
+
 ```{important}
 Please note that the tools discussed here are those that
 we see commonly used in the community. As tools evolve we
@@ -125,10 +169,9 @@ View pyOpenSci peer review check list
 
 ```{figure} ../images/moving-pandas-python-package-github-main-repo.png
 ---
-name: directive-fig
+name: moving-pandas-github-repo-image
 width: 80%
-alt: Image showing the files in the the MovingPandas GitHub repository. Files there include code of conduct.md,
-Contributing.md, license.txt, readme.md.
+alt: Image showing the files in the the MovingPandas GitHub repository. Files in the image include code of conduct.md contributing.md license.txt and readme.md.
 ---
 An example from the MovingPandas GitHub repository with all of the major files in it including CONTRIBUTING.md, README.md, CODE_OF_CONDUCT.md and a LICENSE.txt file. *(screen shot taken Nov 23 2022)*
 ```

documentation/index.md

@@ -1,7 +1,7 @@
 # The CODE_OF_CONDUCT.md file In Your Python Open Source Package
 
-```{tip}
-## Example Code of Conduct files
+```{admonition} Example Code of Conduct files
+:class: tip
 
 * [SciPy Code of Conduct file - notice they included theirs in their documentation](https://docs.scipy.org/doc/scipy/dev/conduct/code_of_conduct.html)
 * [fatiando code of conduct file](https://github.com/fatiando/community/blob/main/CODE_OF_CONDUCT.md)

documentation/repository-files/code-of-conduct-file.md

@@ -2,8 +2,8 @@
 
 ## What a CONTRIBUTING.md file should contain
 
-```{tip}
-## Example contributing files
+```{admonition} Example contributing files
+:class: tip
 
 * [pyGMT contributing file](https://github.com/GenericMappingTools/pygmt/blob/main/CONTRIBUTING.md)
 * [fatiando verde's contributing file](https://github.com/fatiando/verde/blob/main/CONTRIBUTING.md)

documentation/repository-files/contributing-file.md

@@ -15,7 +15,7 @@ It's also helpful to specify the types of tests you request if a contributor sub
 
 If you have time to document it, it's also helpful to document your maintainer workflow and release processes.
 
-### Why a development guide is important
+## Why a development guide is important
 
 It's valuable to have a development guide, in the
 case that you wish to:

documentation/repository-files/development-guide.md

@@ -4,17 +4,6 @@ In this section of the Python packaging guide, we review all of the files that
 you should have in your Python package repository. Your Python package should,
 at a minimum have the following files:
 
-```{toctree}
-:maxdepth: 2
-
-Intro <self>
-README file <readme-file-best-practices.md>
-Contributing File <contributing-file.md>
-Code of Conduct File <code-of-conduct-file.md>
-Development Guide <development-guide.md>
-LICENSE files <license-files.md>
-```
-
 The files mentions above (README, Code of Conduct, license
 file, etc) are used as a measure of package community health
 on many online platforms. Below, you can see an example how Github
@@ -23,7 +12,7 @@ all GitHub repositories.
 
 ```{figure} /images/moving-pandas-python-package-github-community-standards.png
 ---
-name: directive-fig
+name: moving-pandas-github-community
 width: 80%
 alt: Image showing that the MovingPandas GitHub repository community health page with green checks next to each file including a description, README, code of conduct, contributing, license and issue templates. Note that Security policy has a yellow circle next to it as that is missing from the repo.
 ---
@@ -36,7 +25,7 @@ in the Github repo as a measure of community health.
 
 ```{figure} /images/moving-pandas-python-package-snyk-health.png
 ---
-name: directive-fig
+name: moving-pandas-snyk
 width: 80%
 alt: Screenshot of the Snyk page for movingpandas. It shows that the repository has a README file, contributing file, code of conduct. It also shows that it has 30 contributors and no funding. The package health score is 78/100.
 ---

documentation/repository-files/intro.md

@@ -10,7 +10,7 @@ by the Open Software Initiative (OSI). OSI's website has a
 
 If you choose your license through GitHub, you can also automatically get a copy of the license file to add to your repository.
 
-### Important: make sure that you closely follow the guidelines outlines by the License that you chose
+## Important: make sure that you closely follow the guidelines outlines by the License that you chose
 
 Every license has different guidelines in terms of what code
 you can use in your package and also how others can (or can not) use the code in your package.

documentation/repository-files/license-files.md

@@ -16,12 +16,9 @@ health on sites such as:
 
 ```{figure} /images/pandera-python-package-readme-github.png
 ---
-name: directive-fig
+name: pandera-readme
 width: 80%
-alt: README landing page screenshot for the Pandera package. It has the pandera logo at the top - which has two arrows in a chevron pattern pointing downward within a circle. Subtitle: statistical data testing toolkit. A data validation library for scientists, engineering, and analytics seeking correctness.
-Below that are a series of badges including CI tests passing, docs passing, version of pandera on pypi (0.13.4), MIT license and that it has been pyOpenSci peer reviewed. There are numerous badges below that.
-Finally below the badges the text reads:
-Pandera provides a flexible and expressive API for performing data validation on dataframe-like objects to make data processing pipelines more readable and robust.
+alt: README landing page screenshot for the Pandera package. It has the Pandera logo at the top - which has two arrows in a chevron pattern pointing downward within a circle. Subtitle is statistical data testing toolkit. A data validation library for scientists, engineering, and analytics seeking correctness. Below that are a series of badges including CI tests passing, docs passing, version of Pandera on pypi (0.13.4), MIT license and that it has been pyOpenSci peer reviewed. There are numerous badges below that. Finally below the badges the text says, Pandera provides a flexible and expressive API for performing data validation on dataframe-like objects to make data processing pipelines more readable and robust.
 ---
 Your GitHub repository landing page highlights the README.md file. Here you can see the README.md file for the pyOpenSci package [Pandera](https://github.com/unionai-oss/pandera). *(screen shot taken Nov 23 2022)*
 ```
@@ -138,8 +135,8 @@ Include descriptive links to:
 * The package's documentation page.
 * Short tutorials that demonstrate application of your package.
 
-```{tip}
-### Too Much Of A Good Thing
+```{admonition} Too Much Of A Good Thing
+:class: tip
 
 Try to avoid including several tutorials in the README.md file itself. This too will overwhelm the user with information.
 
@@ -167,8 +164,8 @@ Finally be sure to include instructions on how to cite your package.
 Citation should include the DOI that you want used when citing your package,
 and any language that you'd like to see associated with the citation.
 
-```{tip}
-### README Resources
+```{tip} README Resources
+:class: tip
 
 Below are some resources on creating great README.md files that you
 might find helpful.

documentation/repository-files/readme-file-best-practices.md

@@ -8,7 +8,7 @@ to get started using your package. Ideally, those tutorials
 also can be run from start to finish providing a second set of
 checks (on top of your test suite) to your package's code base.
 
-In the [documentation tools page](python-package-documentation-tools) we talk about two Sphinx extensions (`sphinx-gallery` and `nbsphinx`)
+On this page, we review two Sphinx extensions (`sphinx-gallery` and `nbsphinx`)
 that  allow you to create reproducible tutorials that are run
 when your Sphinx documentation builds.
 
@@ -43,7 +43,7 @@ your documentation, the gallery extension:
 
 ```{figure} /images/sphinx-gallery-overview.png
 ---
-name: directive-fig
+name: sphinx-gallery
 width: 80%
 alt: Image showing the gallery output provided by sphinx-gallery where each tutorial is in a grid and the tutorial thumbnails are created from a graphic in the tutorial.
 ---
@@ -55,7 +55,7 @@ Below you can see what a tutorial looks like created with sphinx-gallery.
 
 ```{figure} /images/sphinx-gallery-tutorial.png
 ---
-name: directive-fig
+name: spinx-gallery-tutorial
 width: 80%
 alt: Image showing ta single tutorial from Sphinx gallery. The tutorial shows a simple matplotlib created plot and associated code.
 ---

documentation/write-user-documentation/create-package-tutorials.md

@@ -147,7 +147,7 @@ def extent_to_json(ext_obj):
 
 ```{figure} /images/sphinx-rendering-extent-to-json-earthpy.png
 ---
-name: directive-fig
+name: earthpy-json-example
 width: 80%
 ---
 Using the above NumPy format docstring in sphinx, the autodoc extension will
@@ -193,15 +193,17 @@ def add_me(aNum, aNum2):
     -------
         Prints the integer that you provide the function.
 
+    Examples
+    --------
+    Below you can see how the `print_me` function will print a number that
+    you provide it.
+
+    >>> add_me(1+3)
+    4
+
     """
-   return aNum + aNum2
 
-Examples
---------
-Below you can see how the `print_me` function will print a number that
-you provide it.
+    return aNum + aNum2
 
->>> add_me(1+3)
-4
 
 ```

documentation/write-user-documentation/document-your-code-api-docstrings.md

@@ -57,7 +57,7 @@ page to the following elements:
 
 ```{figure} /images/geopandas-documentation-landing-page.png
 ---
-name: directive-fig
+name: geopandas-landing
 width: 80%
 alt: Image showing the landing page for GeoPandas documentation which has 4 sections including Getting started, Documentation, About GeoPandas, Community.
 ---

documentation/write-user-documentation/get-started.md

@@ -13,14 +13,3 @@ easier such as:
 * autodoc to automagically populate documentation for your code's functions,
 classes, methods and attributes (API documentation) and
 * sphinx gallery for tutorials.
-
-## User-facing documentation sections
-
-```{toctree}
-:maxdepth: 2
-
-Intro <self>
-Create Your Docs <get-started>
-Document Your Code (API) <document-your-code-api-docstrings.md>
-Create Package Tutorials <create-package-tutorials.md>
-```