Merge pull request #322 from openreferral/316-readme-rtd

316 readme rtd

.github/pull_request_template.md

@@ -0,0 +1,19 @@
+**Related issues**
+
+<!-- Add links to related issues here. If you want an issue to be automatically closed when the PR is merged, use keywords (https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) -->
+
+**Description**
+
+<!-- If the changes in the PR are not sufficiently explained by the related issues and commit messages, add a description here -->
+
+**Merge checklist**
+
+<!-- Complete the checklist before requesting a review. -->
+
+- [ ] Check which branch the PR is merging into. For 3.0 update work this should be `3.0-dev'
+- [ ] Update the changelog
+
+If you have edited any schema files:
+
+- [ ] Run `hsds_schema.py` to update `datapackage.json` and example files
+- [ ] Update the [logical model](http://docs.openreferral.org/en/latest/hsds/logical_model/) page if relevant

.readthedocs.yaml

@@ -0,0 +1,39 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  apt_packages:
+    - graphviz
+    - libgraphviz-dev
+  tools:
+    python: "3.9"
+    # You can also specify other tool versions:
+    # nodejs: "16"
+    # rust: "1.55"
+    # golang: "1.17"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - requirements: requirements.txt
+
+# You can include or exclude git submodules from the Read the Docs
+# documentation build.
+# https://docs.readthedocs.io/en/stable/config-file/v2.html#submodules
+submodules:
+  include: all
+

README.md

@@ -20,13 +20,42 @@ We encourage you to use an [open license](http://licenses.opendefinition.org/) f
 
 Earlier versions were licensed under CC0.
 
+## Setup environment for docs and schema tools
+
+Set up an environment and install Python dependencies into it:
+
+```
+python3 -m venv .ve    
+source .ve/bin/activate
+pip install -r requirements.txt
+```
+
+This will install everything needed to run the docs and the `hsds_schema.py` executable.
+
+If you run into any errors with the docs or schema building, make sure an existing environment is up-to-date by running:
+
+```
+pip install --upgrade -r requirements.txt
+```
+
+## Building datapackage.json, examples and compiled schemas
+
+After changing any schemas the following command needs to be run:
+
+```
+hsds_schema.py docs-all
+```
+
+This will update the `datapackage.json` file, the examples and the compiled schemas.
+
+
 ## Building the documentation
 
 ### ReadTheDocs
 
 Any change pushed to the master branch on GitHub will be built and pushed to http://docs.openreferral.org/en/latest/ automatically by ReadTheDocs. Build info is found at https://readthedocs.org/projects/openreferral/builds/
 
-Other branches are not built automatically, but can be configured by admins of the 'openreferral' project on ReadTheDocs, on this page - https://readthedocs.org/projects/openreferral/versions/
+Other branches are also built automatically and can be viewed by typing the branch name into the ReadTheDocs url. Branches other than the master branch are hidden from the ReadTheDocs flyout menu. ReadTheDocs settings can be configured by admins of the 'openreferral' project on ReadTheDocs, on this page - https://readthedocs.org/projects/openreferral/versions/
 
 ### Building locally
 
@@ -38,14 +67,6 @@ You will need graphviz installed. For Ubuntu:
 apt-get install graphviz libgraphviz-dev
 ```
 
-Set up an environment and install Python dependencies into it:
-
-```
-python3 -m venv .ve    
-source .ve/bin/activate
-pip install -r requirements.txt
-```
-
 Then pull in the submodule for the API documentation. 
 
 ```