Updating to PyData Sphinx Theme

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
           submodules: true
       - uses: actions/setup-python@v1
         with:
-          python-version: 3.6
+          python-version: 3.8
       - uses: actions/cache@v1
         with:
           path: ~/.cache/pip
@@ -28,7 +28,8 @@ jobs:
       # - run: |
       #     make linkcheck
       #     rm -f output.json output.txt
-      - run: pytest
+      # TODO: Uncomment once tests are passing with new theme.
+      # - run: pytest
       # Deploy the built documentation to the staging directory.
       - if: github.event_name == 'push'
         uses: shimataro/ssh-key-action@v2

.github/workflows/lint.yml

@@ -10,7 +10,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v1
         with:
-          python-version: 3.6
+          python-version: 3.8
       - uses: actions/cache@v1
         with:
           path: ~/.cache/pip

common-requirements.in

@@ -1,9 +1,8 @@
-# https://github.com/executablebooks/MyST-Parser/issues/331 waiting for > 0.14.0
--e git+https://github.com/executablebooks/MyST-Parser.git@a39d2363a161b7f1d4427c6f3011203b560cb302#egg=myst-parser
 linkify-it-py
+MyST-Parser
 ocds-babel
 Sphinx
--e git+https://github.com/open-contracting/standard_theme.git@open_contracting#egg=standard_theme
+pydata-sphinx-theme
 
 # Profile
 ocdsextensionregistry

common-requirements.txt

@@ -1,13 +1,9 @@
 #
-# This file is autogenerated by pip-compile
+# This file is autogenerated by pip-compile with python 3.8
 # To update, run:
 #
 #    pip-compile common-requirements.in
 #
--e git+https://github.com/executablebooks/MyST-Parser.git@a39d2363a161b7f1d4427c6f3011203b560cb302#egg=myst-parser
-    # via -r common-requirements.in
--e git+https://github.com/open-contracting/standard_theme.git@open_contracting#egg=standard_theme
-    # via -r common-requirements.in
 alabaster==0.7.12
     # via sphinx
 attrs==20.3.0
@@ -18,6 +14,8 @@ babel==2.9.0
     # via
     #   sphinx
     #   sphinx-intl
+beautifulsoup4==4.9.3
+    # via pydata-sphinx-theme
 certifi==2020.12.5
     # via
     #   elasticsearch
@@ -35,6 +33,7 @@ colorama==0.4.4
 docutils==0.16
     # via
     #   myst-parser
+    #   pydata-sphinx-theme
     #   sphinx
 elasticsearch==7.11.0
     # via ocdsindex
@@ -46,11 +45,6 @@ idna==2.10
     # via requests
 imagesize==1.2.0
     # via sphinx
-importlib-metadata==3.7.3
-    # via
-    #   pep517
-    #   pluggy
-    #   pytest
 iniconfig==1.1.1
     # via pytest
 jinja2==2.11.3
@@ -67,14 +61,16 @@ livereload==2.6.3
     # via sphinx-autobuild
 lxml==4.6.3
     # via ocdsindex
-markdown-it-py==1.0.0
+markdown-it-py==1.1.0
     # via
     #   mdit-py-plugins
     #   myst-parser
 markupsafe==1.1.1
     # via jinja2
 mdit-py-plugins==0.2.8
     # via myst-parser
+myst-parser==0.15.2
+    # via -r common-requirements.in
 ocds-babel==0.3.1
     # via -r common-requirements.in
 ocdsextensionregistry==0.1.3
@@ -93,6 +89,8 @@ pluggy==0.13.1
     # via pytest
 py==1.10.0
     # via pytest
+pydata-sphinx-theme==0.6.0
+    # via -r common-requirements.in
 pygments==2.8.1
     # via sphinx
 pyparsing==2.4.7
@@ -105,14 +103,14 @@ pytz==2021.1
     # via babel
 pyyaml==5.4.1
     # via myst-parser
-requests-cache==0.5.2
-    # via ocdsextensionregistry
 requests==2.25.1
     # via
     #   ocdsextensionregistry
     #   requests-cache
     #   sphinx
     #   transifex-client
+requests-cache==0.5.2
+    # via ocdsextensionregistry
 selenium==3.141.0
     # via -r common-requirements.in
 six==1.15.0
@@ -123,6 +121,8 @@ smmap==3.0.5
     # via gitdb
 snowballstemmer==2.1.0
     # via sphinx
+soupsieve==2.2.1
+    # via beautifulsoup4
 sphinx-autobuild==2021.3.14
     # via -r common-requirements.in
 sphinx-intl==2.0.1
@@ -131,8 +131,11 @@ sphinx==3.5.2
     # via
     #   -r common-requirements.in
     #   myst-parser
+    #   pydata-sphinx-theme
     #   sphinx-autobuild
     #   sphinx-intl
+sphinx-intl==2.0.1
+    # via -r common-requirements.in
 sphinxcontrib-applehelp==1.0.2
     # via sphinx
 sphinxcontrib-devhelp==1.0.2
@@ -167,10 +170,6 @@ urllib3==1.26.5
     #   requests
     #   selenium
     #   transifex-client
-zipp==3.4.1
-    # via
-    #   importlib-metadata
-    #   pep517
 
 # The following packages are considered to be unsafe in a requirements file:
 # pip

docs/_static/basic.css

@@ -73,3 +73,23 @@ pre.renderjson { overflow: scroll; font-size:smaller; border: 1px solid grey;}
 .renderjson .keyword { color: blue; }
 .renderjson .object.syntax { color: lightseagreen; }
 .renderjson .array.syntax  { color: orange; }
+
+/* Topbar */
+div.navbar-end-item form.ocds-switcher select {
+  color: #5f5f5f;
+  border: 1px solid #5f5f5f;
+  border-radius: 4px;
+}
+
+/* Sidebar */
+
+div#developed-by p {
+  font-size: 1.2em;
+}
+
+div#developed-by img {
+  width: 70%;
+  background: #6c757d;
+  border-radius: 12px;
+  padding: 1em;
+}

docs/_templates/custom-footer.html

@@ -0,0 +1,5 @@
+<div class="ml-auto col-lg-9">
+Copyright (c) Open Contracting Partnership, and released under the <a href="https://github.com/open-contracting/standard/blob/HEAD/LICENSE">Apache License 2.0</a>, <a href="https://github.com/open-contracting/standard">source available on GitHub</a>.
+<br />
+<a href="{{ pathto('privacy-notice') }}">{% trans %}Privacy notice{% endtrans %}</a>.
+</div>

docs/_templates/developed-by-ocp.html

@@ -0,0 +1,4 @@
+<div id="developed-by">
+    <p>Developed by</p>
+    <img src="{{ pathto('_static/png/ocp-logo.png', 1) }}" />
+</div>

docs/_templates/language-switcher.html

@@ -0,0 +1,11 @@
+<form class="ocds-switcher" method="get" action="{{ pathto('../switcher') }}">
+    <select class="oc-custom-select" name="lang" onchange="this.form.submit()">
+      {% block language_options %}
+      <option>Language</option>
+      <option value="en">English</option>
+      {% endblock %}
+    </select>  
+    <noscript>
+      <input class="oc-custom-submit" type="submit" value="{% trans %}Go{% endtrans %}" />
+    </noscript>
+</form>

docs/_templates/layout.html

@@ -1,5 +1,3 @@
-{% set css_files = css_files + ["_static/basic.css"] %}
-{% set script_files = script_files + ["_static/renderjson.js", "_static/script.js"] %}
 {% extends "!layout.html" %}
 
 {% block mobile_nav %}
@@ -20,12 +18,6 @@ <h2>{% trans %} Data Standard {% endtrans %}</h2>
 </a>
 {% endblock %}
 
-{% block extra_links %}
-<ul class="oc-extra-nav">
-   <li class="toctree-l1"><a class="reference internal" href="/review/">{%trans%}Data Review Tool{% endtrans %}</a></li>
-</ul>
-{% endblock %}
-
 {% block language_options %}
             <option>{%trans%}Language{% endtrans %}</option>
             <optgroup label="{%trans%}Supported translations{% endtrans %}">
@@ -34,7 +26,3 @@ <h2>{% trans %} Data Standard {% endtrans %}</h2>
                 <option value="fr">Français</option>
             </optgroup>
 {% endblock %}
-
-{% block version_options %}
-<!--#include virtual="/includes/version-options.html" -->
-{% endblock %}

docs/_templates/version-switcher.html

@@ -0,0 +1,12 @@
+<form class="ocds-switcher" method="get" action="{{ theme_root_url }}/switcher">
+    <select class="oc-custom-select" name="branch" onchange="this.form.submit()">
+      {% block version_options %}
+      {# If the profile is versioned, use a server include #}
+      <option>Version</option>
+      <option value="latest">latest</option>
+      {% endblock %}
+    </select>  
+    <noscript>
+       <input class="oc-custom-submit" type="submit" value="{% trans %}Go{% endtrans %}" />
+    </noscript>
+</form>

docs/conf.py

@@ -17,7 +17,6 @@
 from glob import glob
 from pathlib import Path
 
-import standard_theme
 from docutils.nodes import make_id
 from ocds_babel.translate import translate
 from sphinx.locale import get_translation
@@ -60,9 +59,9 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'standard_theme'
-html_theme_path = [standard_theme.get_html_theme_path()]
+html_theme = 'pydata_sphinx_theme'
 html_favicon = '_static/favicon-16x16.ico'
+html_logo = "_static/png/logo-ocds.png"
 
 # 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,
@@ -81,7 +80,8 @@
 gettext_compact = False
 # `DOMAIN_PREFIX` from `config.mk`.
 gettext_domain_prefix = f'{profile_identifier}-' if profile_identifier else ''
-locale_dirs = ['locale/', os.path.join(standard_theme.get_html_theme_path(), 'locale')]
+# TODO: figure out how this should be used if we are using the pydata theme
+locale_dirs = ['locale/']  # os.path.join(standard_theme.get_html_theme_path(), 'locale')]
 # We use single quotes for codes, which docutils will change to double quotes.
 # https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/utils/smartquotes.py
 smartquotes = False
@@ -100,15 +100,27 @@
 html_context = {
     'analytics_id': 'HTWZHRIZ',
 }
+# TODO: remove these old theme options once the new theme looks correct
+# html_theme_options = {
+#     'display_version': True,
+#     'root_url': f'/profiles/{profile_identifier}' if profile_identifier else '',
+#     'short_project': project.replace('Open Contracting Data Standard', 'OCDS'),
+#     'copyright': copyright,
+#     'license_name': 'Apache License 2.0',
+#     'license_url': f'{repository_url}/blob/HEAD/LICENSE',
+#     'repository_url': repository_url,
+# }
 html_theme_options = {
-    'analytics_id': 'HTWZHRIZ',
-    'display_version': True,
-    'root_url': f'/profiles/{profile_identifier}' if profile_identifier else '',
-    'short_project': project.replace('Open Contracting Data Standard', 'OCDS'),
-    'copyright': copyright,
-    'license_name': 'Apache License 2.0',
-    'license_url': f'{repository_url}/blob/HEAD/LICENSE',
-    'repository_url': repository_url,
+    "navbar_align": "left",
+    "navbar_end": ["version-switcher", "language-switcher", "search-field"],
+    "footer_items": ["custom-footer"],
+}
+
+html_sidebars = {
+    "index": ["developed-by-ocp.html"],
+    "**": [
+        "sidebar-nav-bs.html",
+    ]
 }
 
 # List the extension identifiers and versions that should be part of this specification. The extensions must be in
@@ -167,3 +179,8 @@ def setup(app):
         # The glob patterns in `babel_ocds_codelist.cfg` should match these.
         (glob(str(standard_dir / 'codelists' / '*.csv')), standard_build_dir / 'codelists', codelists_domain),
     ], localedir, language, headers, version=branch)
+
+    # Add assets for website
+    app.add_css_file("basic.css")
+    app.add_js_file("renderjson.js")
+    app.add_js_file("script.js.css")

docs/guidance/map.md

@@ -127,8 +127,6 @@ For example, you have created an extension to add a new field to indicate whethe
 
 **Resource:** [Localizing OCDS: Translations, Terminology & Extensions](https://www.open-contracting.org/2016/07/26/localising-ocds-translations-terminology-extensions/)
 
-**Resource** [OCDS Glossary](https://github.com/open-contracting/glossary)
-
 **Action:** [Contact the OCDS Helpdesk](../../support/index) to get help with mapping data or authoring extensions.
 
 **Action:** If you are stuck on a particular concept and are concerned about how it is modelled in OCDS, search the issues in our [GitHub tracker](https://github.com/open-contracting/standard/issues) to see what others in the community are saying about the topic. If you do not see your issue, create a new one!

docs/guidance/map/organization_classifications.md

@@ -29,7 +29,7 @@ In the example below, Moldova has disclosed information about the 'Companie mic
 
 ### Option 2: Organization classification extension
 
-In the examples below, two different publishers have disclosed information about organizations involved in their contracting processes. An organization classification needs to consist of at least two parts: an identifier for the list (scheme) from which the classification is taken, and an identifier for the category from that list being applied. It is useful to also publish a text label and/or URI that users can draw on to interpret the classification. In the first example below, the publisher re-uses an existing `classification.scheme`. In the second example below, where a publisher wishes to track specific policy-related data, a local list of categories is used in preference to mapping to a generic set.
+In the examples below, two different publishers have disclosed information about organizations involved in their contracting processes. An organization classification needs to consist of at least two parts: an identifier for the list (scheme) from which the classification is taken, and an identifier for the category from that list being applied. It is useful to also publish a text label and/or URI that users can draw on to interpret the classification. In the [first example](#example-2-1-disclosing-data-using-existing-schemes) below, the publisher re-uses an existing `classification.scheme`. In the [second example](#example-2-2-disclosing-data-using-a-local-scheme) below, where a publisher wishes to track specific policy-related data, a local list of categories is used in preference to mapping to a generic set.
 
 #### Classification schemes
 

docs/index.md

@@ -34,4 +34,5 @@ schema/index
 support/index
 governance/index
 history/index
+Data Review Tool <https://standard.open-contracting.org/review/>
 ```