Merge pull request #918 from kcormi/versioning_docs

Changes to mkdocs and CI for using mike to version the docs

.github/workflows/docs.yml

@@ -18,11 +18,8 @@ jobs:
         python-version: 3.8
     - name: Build documentation
       run: |
-        python3 -m pip install mkdocs pymdown-extensions mkdocs-material
-        mkdocs build --verbose --clean
-    - name: Deploy documentation
-      uses: peaceiris/actions-gh-pages@v3
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./site
-
+        python3 -m pip install mkdocs pymdown-extensions mkdocs-material mike
+        git fetch origin gh-pages --depth=1
+        git config user.name ci-bot
+        git config user.email [email protected]
+        mike deploy --push latest 

contributing.md

@@ -82,10 +82,10 @@ The documentation files are all under the `docs/` folder.
 Which pages get included in the site, and other configuration details are set in the `mkdocs.yml` file.
 
 In order to check the documentation rendering (features such as latex math rendering, etc) locally, you can generate the site on your local computer and check it in your browser.
-To do so, after [installing mkdocs](https://www.mkdocs.org/getting-started/) and [pymdown extensions](https://facelessuser.github.io/pymdown-extensions/installation/) and the [cinder theme](https://sourcefoundry.org/cinder/) via:
+To do so, after [installing mkdocs](https://www.mkdocs.org/getting-started/), [pymdown extensions](https://facelessuser.github.io/pymdown-extensions/installation/), the [material theme](https://squidfunk.github.io/mkdocs-material/), and [mike](https://github.com/jimporter/mike) (for versioning) via:
 
 ```
-python -m pip install mkdocs pymdown-extensions mkdocs-cinder
+python -m pip install mkdocs pymdown-extensions mkdocs-cinder mike
 ```
 
  you can do:
@@ -97,6 +97,14 @@ mkdocs serve
 
 from the main repository directory. mkdocs will then print a link you can open to check the page generated in your browser.
 
+This will serve the current version of the documentation. For the versioned documentation, where the documentation corresponds to a certain tag of the code, mike is used. Mike performs pushes to the `gh-pages` branch of the repository, and sets up certain commits to be accessible as the tagged version of the docs. For adding a new tagged version to the documentation you need to do:
+
+```
+mike deploy <version> <alias>
+```
+
+Note that this will only affect your *local* copy of the gh-pages documentation. In order to view the pages locally you can use `mike serve` instead of `mkdocs serve`.
+
 **NOTE:** mkdocs builds that use internal links (or images, etc.) with absolute paths will work for local deployment, but will break when deployed to the public documentations pages. 
 Please ensure you use relative paths. Currently, this is the only known feature where the behvaiour differs between local mkdocs and public page deployment. 
 If you'd like to test the deployment directly, the suggested method is to set up a docs page using your personal github account; this should mimic the exact settings of the official page.

docs/overrides/main.html

@@ -0,0 +1,10 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  You're not viewing the latest version.
+  <a href="{{ '../' ~ base_url }}"> 
+
+
+    <strong>Click here to go to latest.</strong>
+  </a>
+{% endblock %}

docs/part5/longexercise.md

@@ -634,7 +634,7 @@ While it is perfectly fine to just list the relevant nuisance parameters in the
 [group name] group = uncertainty_1 uncertainty_2 ... uncertainty_N
 ```
 
-** Tasks and questions: **
+**Tasks and questions:**
 
   - Take our stat+syst split one step further and separate the systematic part into two: one part for hadronic tau uncertainties and one for all others.
   - Do this by defining a `tauID` group in the datacard including the following parameters: `CMS_eff_t`, `CMS_eff_t_highpt`, and the three `CMS_scale_t_X` uncertainties.

mkdocs.yml

@@ -35,6 +35,7 @@ theme:
         name: material
         logo: logo.png
         favicon: logo.png
+        custom_dir: docs/overrides
         features: 
             - content.code.copy
             - navigation.footer
@@ -48,6 +49,12 @@ theme:
             - search.suggest
             - toc.follow
 
+plugins:
+    - mike
+
+extra:
+    version:
+        provider: mike
 
 extra_css:
   - "mystyle.css"