ADD: Update package theme to furo and add sitemap and opengraph (#13)

* update package theme
* update requirements
* add site map
* remove 503 error codes as generally those links work and ignore genindex.html

Author: lwasser

.github/workflows/build-book.yml

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

_static/pyos.css

@@ -1,93 +1,20 @@
 html, body {
-    font-size: 1.1rem;
+    font-size: 1.02rem;
 }
 
-body p {
-    /* font-family: $header-font; */
-    font-size: 1em;
-    font-family: 'Verdana', sans-serif!important;
-    color: #555!important;
-    line-height: 1.5em;
-}
-
-h1, h2, h3 {
-    font-family: 'Trebuchet MS', sans-serif;
-    color: #333!important;
+.admonition {
+    margin-top: 40px;
+    margin-bottom: 40px;
 }
 
 h1 {
-    padding-bottom: 1em!important;
-}
-
-h3 {
-    padding-top: 1.4em;
-    margin-bottom: 14px;
-}
-
-/* hide the right sidebar */
-.col-md-3 .bd-toc .show .noprint {
-    display: none!important;
-}
-
-#main-content {
-    max-width: 80%;
-}
-
-.bd-toc {
-    color: #1abc9c;
-}
-
-@media (min-width: 720px){
-.col-md-3 {
-  flex: 0 0 25%;
-  /* max-width: 25%; */
-  display: none!important;
-    }
-}
-
-
-/* HEADER BLOCK 2 */ 
-div.header__block { 
-color: #222;
+    margin-top: 40px;
+    margin-bottom: 40px;
 }
-
-.announcement div {
-background-color: #ccc;
-} 
-
-.header-item.announcement, .header-item.announcement .noprint {
-    background-color:#ccc;
-}
-
-div .announcement .header-item .noprint, header-item.announcement {
-    background-color: #ccc!important;
-}
-
-/* notes */
-
-div.admonition.note .admonition-title, div.admonition.note .admonition-title::before {
-    background-color: #C1CFD4;
-    color: #222;
-
+h2 {
+    margin-top: 60px;
 }
 
-div.admonition.note {
-    border-color: #C1CFD4;
-    background-color: #E3F4FA;
-}
-
-
-div.admonition.important .admonition-title, div.admonition.important .admonition-title::before {
-background-color: #107762;
-color: #ffffff!important;
-}
-
-div.admonition.important .admonition-title {
-background-color: #107762;
-border-color: #1abc9c;
-}
+h3 {
+    margin-top: 40px}
 
-div.admonition.important {
-    border-color: #0e6654;
-    background-color: #ecfcf9;
-}

conf.py

@@ -24,7 +24,6 @@
 # The full version, including alpha/beta/rc tags
 release = '0.1'
 
-
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -34,7 +33,10 @@
     "myst_nb",
     "sphinx_design",
     "sphinx_copybutton",
-    "sphinx.ext.intersphinx"
+    "sphinx.ext.intersphinx",
+    "sphinx_sitemap",
+    "sphinxcontrib.gtagjs",
+    "sphinxext.opengraph",
 ]
 
 # colon fence for card support in md
@@ -45,16 +47,19 @@
 html_theme_options = {
     "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",
+    #"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. 🚧"
 }
 
-
+# Add analytics to furo theme
+gtagjs_ids = [
+    'UA-141260825-1',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -71,13 +76,15 @@
     "README.md"
     ]
 
+# For sitemap
+html_baseurl = 'https://www.pyopensci.org/package-review-guide/'
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_book_theme'
+html_theme = 'furo'
 html_static_path = ["_static"]
 html_css_files = ["pyos.css"]
 html_title = "pyOpenSci Package Guide"

index.md

@@ -2,6 +2,7 @@
 
 <!-- Github community standards 
 https://github.com/pyOpenSci/python-package-guide/community -->
+
 ## Welcome, Python open source enthusiast! 
 
 Here you will find guidelines for what we look for in your scientific 
@@ -21,19 +22,11 @@ Python package when reviewing. You will also find best practice recommendations
 :class: sd-fs-3
 
 
-<!-- 
-Removing button for the time being
-```{button-ref} start/your-first-book
-:ref-type: doc
+```{button-link} https://www.pyopensci.org/about-peer-review/
 :color: primary
 :class: sd-rounded-pill float-left
-
-
-Get Involved (Maybe a link to a get involved page)
-
-% SVG rendering breaks latex builds for the GitHub badge, so only include in HTML
-``` 
--->
+Learn about our open peer review process
+```
 
 ```{only} html
 ![GitHub release (latest by date)](https://img.shields.io/github/v/release/pyopensci/python-package-guide?color=purple&display_name=tag&style=plastic)
@@ -69,7 +62,7 @@ covered include: README files, tutorials and full docs.
 :link-type: doc
 :class-header: bg-light
 
-✨ Coming soon... ✨
+✨ Package Structure & Code ✨
 ^^^
 <!-- 
 Get a basic overview of our open peer review process for Python scientific open source software. -->
@@ -113,21 +106,34 @@ Good meets the requirements. Going beyond the minimum can make package maintenan
 This guide is now a work in progress. If you have ideas of things you'd like 
 to see here, [we invite you to open an issue on GitHub that details any changes or additions that you'd like to see.](https://github.com/pyOpenSci/python-package-guide/issues).
 
+
 ```{toctree}
 :hidden:
 :caption: Documentation
 
 Intro to Documentation <documentation/index>
 The README File <documentation/create-readme-files.md>
-Package docs & tutorials <documentation/package-documentation-tutorials>
+README Files <documentation/readme-files>
+Package documentation <documentation/package-documentation-sphinx>
 Contributing & license files <documentation/contributing>
 ```
 
 ```{toctree}
 :hidden:
-:caption: Package structure
-I don't work <package-structure-code/index.md>
-I work <package-structure-code/code-structure-style.md>
+:caption: Package structure & code style
+
+Intro <package-structure-code/intro>
+package-structure-code/code-structure-style
+package-structure-code/release
+package-structure-code/overview
+package-structure-code/collaboration
+```
+
+```{toctree}
+:hidden:
+:caption: Code Style & Structure
+
+code-style-structure/index
 ```
 
 ```{toctree}
@@ -137,14 +143,7 @@ testing-infrastructure/test-code
 testing-infrastructure/continuous-integration
 ```
 
-<!-- 
-Removing button for the time being
-```{button-ref} start/your-first-book
-:ref-type: doc
-:color: primary
-:class: sd-rounded-pill float-left
-Get Involved (Maybe a link to a get involved page)
-``` -->
+
 
 
 

requirements.txt

@@ -1,8 +1,14 @@
 #ipython
-sphinx-book-theme
-myst-parser[linkify]
+furo
 myst-nb
 sphinx
 sphinx-autobuild
 sphinx-copybutton
 sphinx-design
+# XML feed for analytics
+sphinx-sitemap
+# Support for social / adds meta tags
+sphinxext-opengraph
+sphinx-inline-tabs
+# Support for GA
+sphinxcontrib-gtagjs