Merge pull request #157 from robotpy/rtd

Update documentation

Author: virtuald

.readthedocs.yml

@@ -0,0 +1,15 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+python:
+  install:
+  - requirements: docs/requirements.txt
+  - method: pip
+    path: .

docs/conf.py

@@ -15,6 +15,7 @@
 # sys.path.insert(0, os.path.abspath('.'))
 
 import sphinx_rtd_theme
+import importlib.metadata
 
 
 # -- Project information -----------------------------------------------------
@@ -24,7 +25,7 @@
 author = "Benjamin Fogle"
 
 # The full version, including alpha/beta/rc tags
-release = "0.7"
+release = importlib.metadata.distribution("crossenv").version
 
 
 # -- General configuration ---------------------------------------------------
@@ -49,9 +50,8 @@
 # a list of builtin themes.
 #
 html_theme = "sphinx_rtd_theme"
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+html_static_path = []

docs/quickstart.rst

@@ -4,6 +4,13 @@
 Cross compiling can be challenging, and crossenv is focused only on one
 particular piece. As such, this section is not a complete guide.
 
+.. seealso:: For CI purposes the crossenv project builds several docker images
+             that contain appropriately configured build and host pythons for
+             cross compilation. You may find these to be a useful starting
+             point.
+
+             https://github.com/robotpy/crossenv-ci-images
+
 Build build-python
 ------------------
 
@@ -31,9 +38,10 @@ builds may require more. It depends very much on your specific requirements.)
 Build or obtain host-python
 ---------------------------
 
-In this quick start we assume you are building host-python yourself. In other
-cases you may be targeting a pre-built system image. A pre-built image has it's
-own challenges, which are covered elsewhere.
+In this quick start we assume you are building host-python yourself. It is not
+a requirement to use the actual python that is on the target host -- and in fact
+we don't recommend it! The primary requirement is that the version must match the
+version of build-python.
 
 You will need to build any host dependencies beforehand. So, for example, if
 you want host-python to be able to communicate over a network, you may need to

docs/requirements.txt

@@ -1,2 +1,2 @@
-Sphinx==2.4.3
-sphinx_rtd_theme
+sphinx >= 3.0
+sphinx-rtd-theme