Merge pull request #1628 from choldgraf/myst

switching to myst markdown in docs

Author: consideRatio

doc/doc-requirements.txt

@@ -1,6 +1,6 @@
 pydata_sphinx_theme
 pyyaml
-recommonmark
+myst_parser
 sphinx-autobuild
 sphinx-copybutton
-sphinx
+sphinx<3

doc/source/administrator/advanced.md

@@ -169,13 +169,11 @@ In your `hub.extraConfig`,
 You need to have a `import z2jh` at the top of your `extraConfig` for
 `z2jh.get_config()` to work.
 
-```eval_rst
-.. versionchanged:: 0.8
-
-  `hub.extraConfigMap` used to be required for specifying additional values
-  to pass, which was more restrictive.
-  `hub.extraConfigMap` is deprecated in favor of the new
-  top-level `custom` field, which allows fully arbitrary yaml.
+```{versionchanged} 0.8
+`hub.extraConfigMap` used to be required for specifying additional values
+to pass, which was more restrictive.
+`hub.extraConfigMap` is deprecated in favor of the new
+top-level `custom` field, which allows fully arbitrary yaml.
 ```
 
 ### `hub.extraEnv`

doc/source/administrator/optimization.md

@@ -1,7 +1,4 @@
-```eval_rst
-.. _optimization:
-```
-
+(optimization)=
 # Optimizations
 
 This page contains information and guidelines for improving the reliability,
@@ -74,7 +71,7 @@ situations:
     referring to how a [Helm
     hook](https://docs.helm.sh/developing_charts/#hooks) is used to accomplish
     this, a more informative name would have been *pre-upgrade-image-puller*.
-    
+
     **NOTE**: With this enabled your `helm upgrade` will take a long time if you
     introduce a new image as it will wait for the pulling to complete. We
     recommend that you add `--timeout 600` or similar to your `helm upgrade`
@@ -165,10 +162,7 @@ prePuller:
       tag: 2343e33dec46
 ```
 
-```eval_rst
-.. _efficient-cluster-autoscaling:
-```
-
+(efficient-cluster-autoscaling)=
 ## Efficient Cluster Autoscaling
 
 A [*Cluster
@@ -271,7 +265,7 @@ following:
       kubernetes labels, but this label must be a kubernetes label.
 
     - The taint: `hub.jupyter.org/dedicated=user:NoSchedule`
-    
+
       **NOTE**: You may need to replace `/` with `_` due cloud provider
       limitations. Both taints are tolerated by the user pods.
 

doc/source/conf.py

@@ -20,21 +20,14 @@
 
 from datetime import date
 
-from recommonmark.transform import AutoStructify
 import yaml
 
 
 # -- Sphinx setup function ---------------------------------------------------
 # ref: http://www.sphinx-doc.org/en/latest/extdev/tutorial.html#the-setup-function
 
 def setup(app):
-    app.add_config_value(
-        'recommonmark_config',
-        { 'enable_eval_rst': True, },
-        True,
-    )
-    app.add_stylesheet('custom.css')
-    app.add_transform(AutoStructify)
+    app.add_css_file('custom.css')
 
 
 # -- Project information -----------------------------------------------------
@@ -71,7 +64,7 @@ def setup(app):
 # ones.
 extensions = ['sphinx.ext.mathjax',
               'sphinx_copybutton',
-              'recommonmark']
+              'myst_parser']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

doc/source/customizing/user-management.md

@@ -12,14 +12,11 @@ have to start their server again, and the state of their previous session
 (variables they've created, any in-memory data, etc)
 will be lost. This is known as *culling*.
 
-```eval_rst
-
-.. note::
-
-  In JupyterHub, "inactivity" is defined as no response from the user's
-  browser. JupyterHub constantly pings the user's JupyterHub browser session
-  to check whether it is open. This means that leaving the computer running
-  with the JupyterHub window open will **not** be treated as inactivity.
+```{note}
+In JupyterHub, "inactivity" is defined as no response from the user's
+browser. JupyterHub constantly pings the user's JupyterHub browser session
+to check whether it is open. This means that leaving the computer running
+with the JupyterHub window open will **not** be treated as inactivity.
 ```
 
 To disable culling, put the following into `config.yaml`:
@@ -40,13 +37,10 @@ cull:
   every: <number-of-seconds-this-check-is-done>
 ```
 
-```eval_rst
-
-.. note::
-
-   While JupyterHub automatically runs the culling process, it is not a
-   replacement for keeping an eye on your cluster to make sure resources
-   are being used as expected.
+```{note}
+While JupyterHub automatically runs the culling process, it is not a
+replacement for keeping an eye on your cluster to make sure resources
+are being used as expected.
 ```
 
 ## Admin Users

doc/source/customizing/user-storage.md

@@ -1,7 +1,4 @@
-```eval_rst
-.. _user-storage:
-```
-
+(user-storage)=
 # Customizing User Storage
 
 For the purposes of this guide, we'll describe "storage" as
@@ -48,7 +45,7 @@ In the future, when the user logs back in, JupyterHub will
 detect that the user has a pre-existing `PVC` and will simply
 attach it to their new pod, rather than creating a new `PVC`.
 
-### How can this process break down?
+## How can this process break down?
 
 When Kubernetes uses the `PVC` to create a new user `PV`, it
 is sending a command to the underlying API of whatever cloud
@@ -61,17 +58,15 @@ may be simultaneously attached to a node in your cluster. Check
 your cloud provider for details on the limits of storage
 resources you request.
 
-```eval_rst
-.. note::
-
-   Some cloud providers have a limited number of disks that can be attached to
-   each node. Since JupyterHub allocates one disk per user for
-   persistent storage, this limits the number of users that can be running in
-   a node at any point of time. If you need users to have
-   persistent storage, and you end up hitting this limit, you must use
-   *more* nodes in order to accommodate the disk for each user. In this
-   case, we recommend allocating *fewer* resources per node (e.g. RAM) since
-   you'll have fewer users packed onto a single node.
+```{note}
+Some cloud providers have a limited number of disks that can be attached to
+each node. Since JupyterHub allocates one disk per user for
+persistent storage, this limits the number of users that can be running in
+a node at any point of time. If you need users to have
+persistent storage, and you end up hitting this limit, you must use
+*more* nodes in order to accommodate the disk for each user. In this
+case, we recommend allocating *fewer* resources per node (e.g. RAM) since
+you'll have fewer users packed onto a single node.
 ```
 
 ## Configuration
@@ -199,9 +194,8 @@ singleuser:
     type: none
 ```
 
-```eval_rst
-Next :ref:`apply the changes <apply-config-changes>`.
-```
+Next {ref}`apply the changes <apply-config-changes>`.
+
 
 After the changes are applied, new users will no longer be allocated a
 persistent `$HOME` directory. Any currently running users will still have

doc/source/reference/reference.txt

@@ -1,9 +1,6 @@
 DO NOT EDIT THIS LINE. This file is used in `conf.py to generate schema.md`. Edit below and changes will propagate to the build.
-```eval_rst
-.. _helm-chart-configuration-reference:
-```
-
-# Configuration Reference 
+(helm-chart-configuration-reference)=
+# Configuration Reference
 
 The [JupyterHub Helm
 chart](https://github.com/jupyterhub/zero-to-jupyterhub-k8s) is configurable by
@@ -14,7 +11,5 @@ Below is a description of many *but not all* of the configurable values for the
 Helm chart. To see *all* configurable options, inspect their default values
 defined [here](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/blob/master/jupyterhub/values.yaml).
 
-```eval_rst
 For more guided information about some specific things you can do with
-modifications to the helm chart, see the :ref:`customization-guide`.
-```
+modifications to the helm chart, see the {ref}`customization-guide`.