Merge pull request jupyterhub#1513 from consideRatio/links-in-docs-etc

Correction of warnings from: make html
cgiraldo · Dec 3, 2019 · f4403a4 · f4403a4
2 parents edd3269 + 5a34370
commit f4403a4
Show file tree

Hide file tree

Showing 7 changed files with 42 additions and 7 deletions.
diff --git a/doc/README.md b/doc/README.md
@@ -0,0 +1,31 @@
+# About the documentation
+
+This documentation is automatically built on each commit [as configured on
+ReadTheDocs](https://readthedocs.org/projects/zero-to-jupyterhub/), and made
+available on [z2jh.jupyter.org](https://z2jh.jupyter.org/).
+
+## Intro to the documentation code base
+
+This is not documented properly yet. What should go in this section could be
+what the makefile does, what sphinx is/does, environment.yml vs
+doc-requirements.txt, make.bat vs Makefile, source/conf.py, use of .rst and .md,
+how to use rst in md, what the _templates folder contains and how those are
+used.
+
+Additionally, some foundational RST techniques in play could be useful, but
+perhaps documented in the team-compass and referenced here.
+
+## Local documentation development
+
+To locally develop the documentation, do something like this and visit
+http://localhost:8888. Note that you need to host the content with a webserver
+to avoid links failing, and that you need to rebuild with `make html` to update
+the documentation. The live-server will ensure to update its content based on
+changes though.
+
+```shell
+cd doc
+pip install live-server -r doc-requirements.txt
+make html
+live-server build/html
+```
diff --git a/doc/source/administrator/optimization.md b/doc/source/administrator/optimization.md
@@ -1,3 +1,7 @@
+```eval_rst
+.. _optimization:
+```
+
 # Optimizations
 
 This page contains information and guidelines for improving the reliability,
@@ -321,7 +325,7 @@ for the first time, it is showing the amount of user pods active on five
 different nodes. When the user scheduler was enabled, two nodes were in time
 freed up from user pods and scaled down.
 
-[![](_static/images/user_scheduler.png)](_static/images/user_scheduler.png)
+[![](../_static/images/user_scheduler.png)](../_static/images/user_scheduler.png)
 
 To enable the user scheduler:
 

diff --git a/doc/source/community/index.rst b/doc/source/community/index.rst
@@ -18,7 +18,7 @@ up, managing, and maintaining JupyterHub.
 
 We hope that you will use this section to share deployments with on a variety
 of infrastructure and for different use cases.
-There is also a :doc:`community maintained list <community/users-list>` of users of this
+There is also a :doc:`community maintained list <./users-list>` of users of this
 Guide and the JupyterHub Helm Chart.
 
 Please submit a pull request to add to this section. Thanks.

diff --git a/doc/source/customizing/index.rst b/doc/source/customizing/index.rst
@@ -16,4 +16,4 @@ used configurable helm chart fields.
    user-environment
    user-resources
    user-storage
-   user-management
+   user-management
diff --git a/doc/source/google/step-zero-gcp.rst b/doc/source/google/step-zero-gcp.rst
@@ -116,7 +116,7 @@ your google cloud account.
 
   This is an optional step, for those who want to separate
   user pods from "core" pods such as the Hub itself and others.
-  See :doc:`../optimization` for details on using a dedicated user node pool.
+  See :ref:`optimization` for details on using a dedicated user node pool.
 
   The nodes in this node pool are for the users only. The node pool has
   autoscaling enabled along with a lower and an upper scaling limit. This

diff --git a/doc/source/repo2docker.rst b/doc/source/repo2docker.rst
@@ -145,7 +145,7 @@ to configure JupyterHub to build off of this image:
    .. note::
 
       The contents of your GitHub repository might not show up if you have
-      enabled :doc:`persistent storage <user-storage>`. Disable persistent
+      enabled :ref:`persistent storage <user-storage>`. Disable persistent
       storage if you want the Git repository contents to show up.
 
 9. **Enjoy your new computing environment!**

diff --git a/doc/source/setup-jupyterhub/setup-jupyterhub.rst b/doc/source/setup-jupyterhub/setup-jupyterhub.rst
@@ -188,8 +188,8 @@ Install JupyterHub
    to a browser. JupyterHub is running with a default *dummy* authenticator so
    entering any username and password combination will let you enter the hub.
 
-Congratulations! Now that you have basic JupyterHub running, you can :doc:`extend it
-<extending-jupyterhub>` and :doc:`optimize it <optimization>` in many
+Congratulations! Now that you have basic JupyterHub running, you can :ref:`extend it
+<extending-jupyterhub>` and :ref:`optimize it <optimization>` in many
 ways to meet your needs.
 
 Some examples of customisations are: