Add intersphinx and some docs (#1217)

* Add intersphinx and some docs

* Remove spaces

* Address Jeff comments

docs/Makefile

@@ -30,7 +30,7 @@ shell:
 	@export CONDA_ENV_PROMPT='<{name}>'
 	@echo 'conda activate $(env)'
 
-htmlserve:
+htmlserve: html
 	@echo 'visit docs at http://localhost:8080'
 	python -m http.server -d "$(BUILDDIR)/html/" 8080
 

docs/README.md

@@ -29,3 +29,26 @@ static files like templates and themes, to build the static end result.
 ### Build
 
 To learn how to build the docs, head over the [CONTRIBUTING](../CONTRIBUTING.md) page.
+
+
+## Cross-referencing
+
+You can link to other pages in the documentation by using the `{doc}` role. For example, to link to the `docs/README.md` file, you would use:
+
+```markdown
+{doc}`docs/README.md`
+```
+
+You can also cross-reference the python glossary by using the `{term}` role. For example, to link to the `iterable` term, you would use:
+
+```markdown
+{term}`iterable`
+```
+
+You can also cross-reference functions, methods or data attributes by using the `{attr}` for example:
+
+```markdown
+{py:func}`repr`
+```
+
+This would link to the `repr` function in the python builtins.

docs/conf.py

@@ -36,8 +36,13 @@ extensions = [
     "sphinx_sitemap",
     "sphinxemoji.sphinxemoji",
     "sphinxcontrib.youtube",
+    "sphinx.ext.intersphinx",
 ]
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3.10", None),
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

docs/reference/API/display.md

@@ -2,7 +2,8 @@
 
 ## Parameters
 
-`*values` - the objects to be displayed. String objects are output as-written. For non-string objects, the default content to display is the the object's `repr()`. Objects may implement the following methods to indicate that they should be displayed as a different MIME type. MIME types with a * indicate that the content will be wrapped in the appropriate html tags and attributes before output:
+`*values` - the objects to be displayed. String objects are output as-written. For non-string objects, the default content to display is the the object's {py:func}`repr`. Objects may implement the following methods to indicate that they should be displayed as a different MIME type. MIME types with a * indicate that the content will be wrapped in the appropriate html tags and attributes before output:
+
 
 | Method              | Inferred MIME type     |
 |---------------------|------------------------|