adopt myst

run rst2myst, with minimal manual formatting fixes

docs/conf.py

@@ -23,9 +23,10 @@
     "sphinx_copybutton",
     "sphinxext.opengraph",
     "sphinxext.rediraffe",
+    "myst_parser",
 ]
 root_doc = "index"
-source_suffix = [".rst"]
+source_suffix = [".md"]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -59,6 +60,18 @@
     "doc_path": "docs",
 }
 
+# -- MyST configuration ------------------------------------------------------
+# ref: https://myst-parser.readthedocs.io/en/latest/configuration.html
+#
+myst_heading_anchors = 2
+
+myst_enable_extensions = [
+    # available extensions: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
+    "attrs_inline",
+    "colon_fence",
+    "deflist",
+    "fieldlist",
+]
 
 # -- Options for linkcheck builder -------------------------------------------
 # ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder

docs/contributing/code-review.rst → docs/contributing/code-review.md

@@ -1,37 +1,32 @@
-.. _contributing/code-review:
+(contributing-code-review)=
 
-======================
-Code Review guidelines
-======================
+# Code Review guidelines
 
 This document outlines general guidelines to follow when you are making
 or reviewing a Pull Request.
 
-Have empathy
-============
+## Have empathy
 
-We recommend reading `On Empathy & Pull Requests <https://slack.engineering/on-empathy-pull-requests-979e4257d158>`_
-and `How about code reviews <https://slack.engineering/how-about-code-reviews-2695fb10d034>`_
+We recommend reading [On Empathy & Pull Requests](https://slack.engineering/on-empathy-pull-requests-979e4257d158)
+and [How about code reviews](https://slack.engineering/how-about-code-reviews-2695fb10d034)
 to learn more about being empathetic in code reviews.
 
-Write documentation
-===================
+## Write documentation
 
 If your pull request touches any code, you must write or update documentation
 for it. For this project, documentation is a lot more important than the code.
-If a feature is not documented, it does not exist. If a behavior is not documented, 
-it is a bug. 
+If a feature is not documented, it does not exist. If a behavior is not documented,
+it is a bug.
 
 Do not worry about having perfect documentation! Documentation improves over
 time. The requirement is to have documentation before merging a pull request,
-not to have *perfect* documentation before merging a pull request. If you
+not to have _perfect_ documentation before merging a pull request. If you
 are new and not sure how to add documentation, other contributors will
 be happy to guide you.
 
-See :ref:`contributing/docs` for guidelines on writing documentation.
+See {ref}`contributing/docs` for guidelines on writing documentation.
 
-Write tests
-===========
+## Write tests
 
 If your pull request touches any code, you must write unit or integration tests
 to exercise it. This helps validate & communicate that your pull request works
@@ -48,4 +43,4 @@ add more tests.
 If you are unsure what kind of tests to add for your pull request, other
 contributors to the repo will be happy to help guide you!
 
-See :ref:`contributing/tests` for guidelines on writing tests.
+See {ref}`contributing/tests` for guidelines on writing tests.

docs/contributing/dev-setup.md

@@ -0,0 +1,72 @@
+(contributing-dev-setup)=
+
+# Setting up Development Environment
+
+The easiest & safest way to develop & test TLJH is with [Docker](https://www.docker.com/).
+
+1. Install Docker Community Edition by following the instructions on
+   [their website](https://www.docker.com/community-edition).
+
+2. Clone the [git repo](https://github.com/jupyterhub/the-littlest-jupyterhub) (or your fork of it).
+
+3. Build a docker image that has a functional systemd in it.
+
+   ```bash
+   docker build -t tljh-systemd . -f integration-tests/Dockerfile
+   ```
+
+4. Run a docker container with the image in the background, while bind mounting
+   your TLJH repository under `/srv/src`.
+
+   ```bash
+   docker run \
+     --privileged \
+     --detach \
+     --name=tljh-dev \
+     --publish 12000:80 \
+     --mount type=bind,source=$(pwd),target=/srv/src \
+     tljh-systemd
+   ```
+
+5. Get a shell inside the running docker container.
+
+   ```bash
+   docker exec -it tljh-dev /bin/bash
+   ```
+
+6. Run the bootstrapper from inside the container (see step above):
+   The container image is already set up to default to a `dev` install, so
+   it'll install from your local repo rather than from github.
+
+   ```console
+   python3 /srv/src/bootstrap/bootstrap.py --admin admin
+   ```
+
+> Or, if you would like to setup the admin's password during install,
+> you can use this command (replace "admin" with the desired admin username
+> and "password" with the desired admin password):
+>
+> > ```console
+> > python3 /srv/src/bootstrap/bootstrap.py --admin admin:password
+> > ```
+> >
+> > The primary hub environment will also be in your PATH already for convenience.
+
+1. You should be able to access the JupyterHub from your browser now at
+   [http://localhost:12000](http://localhost:12000). Congratulations, you are
+   set up to develop TLJH!
+
+2. Make some changes to the repository. You can test easily depending on what
+   you changed.
+
+   - If you changed the `bootstrap/bootstrap.py` script or any of its dependencies,
+     you can test it by running `python3 /srv/src/bootstrap/bootstrap.py`.
+   - If you changed the `tljh/installer.py` code (or any of its dependencies),
+     you can test it by running `python3 -m tljh.installer`.
+   - If you changed `tljh/jupyterhub_config.py`, `tljh/configurer.py`,
+     `/opt/tljh/config/` or any of their dependencies, you only need to
+     restart jupyterhub for them to take effect. `tljh-config reload hub`
+     should do that.
+
+{ref}`troubleshooting/logs` has information on looking at various logs in the container
+to debug issues you might have.