developer_docs.md: update based on review comments

GFDRR · Aug 4, 2023 · 1407929 · 1407929
1 parent 032911e
commit 1407929
Showing 1 changed file with 76 additions and 81 deletions.
diff --git a/developer_docs.md b/developer_docs.md
@@ -2,20 +2,20 @@
 
 This page provides the following documentation for developers of the Risk Data Library Standard:
 
-* [How-to guides](#how-to-guides)
-* [Style guides](#style-guides)
-* [Reference documentation](#reference)
+- [How-to guides](#how-to-guides)
+- [Style guides](#style-guides)
+- [Reference documentation](#reference)
 
 ## How-to guides
 
 This section contains the following how-to guides:
 
-* [Propose changes](#propose-changes)
-* [Deploy changes](#deploy-changes)
-* [Set up a local development environment](#set-up-a-local-development-environment)
-* [Build the documentation](#build-the-documentation)
-* [Update requirements](#update-requirements)
-* [Resolve check failures](#resolve-check-failures)
+- [Propose changes](#propose-changes)
+- [Deploy changes](#deploy-changes)
+- [Set up a local development environment](#set-up-a-local-development-environment)
+- [Build the documentation](#build-the-documentation)
+- [Update requirements](#update-requirements)
+- [Resolve check failures](#resolve-check-failures)
 
 ### Propose changes
 
@@ -24,12 +24,14 @@ The preferred approach for making changes to the standard is to use a [local dev
 1. Agree on a proposal in a [GitHub issue](https://github.com/GFDRR/rdl-standard/issues).
 1. Create a branch from the `dev` branch.
 1. Make your changes. Do not use normative keywords in non-normative content. For more information, see [normative and non-normative content in RDLS](https://docs.google.com/document/d/13g1SZO3ZSHbkymtc69lQOu9vB9vlZVZnodAcxC50l1M/edit#).
-1. Run `./manage.py pre-commit`.
-1. [Build the documentation](#build-the-documentation), resolve any errors and preview your changes locally.
-1. Commit your changes to your branch and push it to GitHub. Your changes are available for anyone to preview at [https://rdl-standard.readthedocs.io/en/{branch name}](https://rdl-standard.readthedocs.io/en/{branch name}).
+1. Run `./manage.py pre-commit`. (This step assumes you are working within your [local development environment](#set-up-a-local-development-environment)).
+1. Run `pytest` and [resolve any errors](#resolve-check-failures). (This step assumes you are working within your [local development environment](#set-up-a-local-development-environment))
+1. [Build the documentation](#build-the-documentation), [resolve any errors](#resolve-check-failures) and [preview your changes locally](#build-the-documentation). (This step assumes you are working within your [local development environment](#set-up-a-local-development-environment)).
+1. Commit your changes to your branch and push it to GitHub. Your changes are available for anyone to preview at \[https://rdl-standard.readthedocs.io/en/{branch name}\](https://rdl-standard.readthedocs.io/en/{branch name}).
 1. [Create a pull request](https://github.com/GFDRR/rdl-standard/compare):
-  * Set the base branch to `dev`.
-  * Reference the issue number in the description. 
+
+- Set the base branch to `dev`.
+- Reference the issue number in the description.
 
 Once the pull request is merged, the updated documentation is available to preview at [https://rdl-standard.readthedocs.io/en/dev](https://rdl-standard.readthedocs.io/en/dev).
 
@@ -61,37 +63,39 @@ You can use either `pyenv` or `python3-venv`:
 
 ##### pyenv
 
-(For Mac OS users.)
-
 1. Install [pyenv](https://github.com/pyenv/pyenv). The [pyenv installer](https://github.com/pyenv/pyenv-installer) is recommended.
 1. Create a virtual environment.
-    ```bash
-    pyenv virtualenv rdl-standard
-    ```
+   ```bash
+   pyenv virtualenv rdl-standard
+   ```
 1. Activate the virtual environment
-    ```bash
-    pyenv activate rdl-standard
-    ```
+   ```bash
+   pyenv activate rdl-standard
+   ```
 1. Set the local application-specific virtual environment. Once set, navigating to the `rdl-standard` directory will automatically activate the environment.
-    ```bash
-    pyenv local rdl-standard
-    ```
+   ```bash
+   pyenv local rdl-standard
+   ```
 
 ##### python3-venv
 
 1. Install [python3-venv](https://docs.python.org/3/library/venv.html).
 
-    ```bash
-    sudo apt-get install python3-venv
-    ```
+   ```bash
+   sudo apt-get install python3-venv
+   ```
+
 1. Create a virtual environment.
-    ```bash
-    python3 -m venv .ve
-    ```
+
+   ```bash
+   python3 -m venv .ve
+   ```
+
 1. Activate the virtual environment. You must run this command for each new terminal session.
-    ```bash
-    source .ve/bin/activate
-    ```
+
+   ```bash
+   source .ve/bin/activate
+   ```
 
 #### Install requirements
 
@@ -100,16 +104,6 @@ pip install --upgrade pip setuptools
 pip install -r requirements.txt
 ```
 
-### Run schema tests on local machine
-
-If your system has not already done so [activate a python environment](#create-and-activate-a-python-virtual-environment), and then [install requirements](#install-requirements).
-
-Run:
-
-```bash
-pytest -rs tests
-```
-
 ### Build the documentation
 
 Sphinx, which builds the documentation, doesn’t watch directories for changes. To regenerate the documentation, start an HTML server, and refresh the browser whenever changes are made, run:
@@ -130,19 +124,19 @@ python -m http.server --directory _readthedocs/html
 ### Update requirements
 
 1. Install `pip-tools`.
-    ```bash
-    pip install pip-tools
-    ```
-2. Edit `requirements.in`.
-3. Update `requirements.txt`.
-    ```bash
-    pip-compile
-    ```
-4. Install requirements.
-    ```bash
-    pip-sync requirements.txt
-    ```
-5. Commit your changes.
+   ```bash
+   pip install pip-tools
+   ```
+1. Edit `requirements.in`.
+1. Update `requirements.txt`.
+   ```bash
+   pip-compile
+   ```
+1. Install requirements.
+   ```bash
+   pip-sync requirements.txt
+   ```
+1. Commit your changes.
 
 ### Resolve check failures
 
@@ -153,6 +147,7 @@ If this check fails, run the following command to fix markdown formatting:
 ```bash
 mdformat docs
 ```
+
 #### tests
 
 If this check fails, review the output to identify which test failed:
@@ -181,15 +176,15 @@ Review the warnings to identify and correct the errors. For more information on
 
 ### Changelog style guide
 
-* Use the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
-* Begin each entry with a link to the pull request for the change.
+- Use the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
+- Begin each entry with a link to the pull request for the change.
 
 #### Normative content
 
 Changelog entries should be descriptive:
 
-* Bad entry: Update schema.
-* Good entry: Make `name` required.
+- Bad entry: Update schema.
+- Good entry: Make `name` required.
 
 If changes are made to files under the `schema` directory, it is assumed that corresponding changes were made to files under the `docs` directory. Do not add an entry under the "Documentation" heading if the changes directly correspond to entries under the "Codelists" and/or "Schema" headings.
 
@@ -203,10 +198,10 @@ Changelog entries should be descriptive. Do not add an entry like "Improve prime
 
 This section contains the following reference documentation:
 
-* [GitHub repository](#github-repository)
-* [Sphinx](#sphinx)
-* [Read the Docs](#read-the-docs)
-* [manage.py](#managepy)
+- [GitHub repository](#github-repository)
+- [Sphinx](#sphinx)
+- [Read the Docs](#read-the-docs)
+- [manage.py](#managepy)
 
 ### GitHub repository
 
@@ -224,23 +219,23 @@ Feature branches branch off the `dev` branch, with work merged into the `dev` br
 
 #### Directory structure
 
-* `.github/`: Issue templates and GitHub Actions workflows
-* `docs/`:
-  * `*.md`, `*/*.md`: English documentation text
-  * `conf.py`: Sphinx configuration
-  * `_static/`: CSS and JavaScript for the documentation
-  * `_templates/`: Jinja templates for the documentation
-  * `.tx/`: Transifex configuration (not yet implemented)
-  * `img/`: Images used in the documentation
-  * `locale/`: Translations of the English documentation (not yet implemented)
-* `schema/`: schema-related files
-* `specs/`: TBD
-* `SteeringCommittee/`: Minutes of steering committee meetings
+- `.github/`: Issue templates and GitHub Actions workflows
+- `docs/`:
+  - `*.md`, `*/*.md`: English documentation text
+  - `conf.py`: Sphinx configuration
+  - `_static/`: CSS and JavaScript for the documentation
+  - `_templates/`: Jinja templates for the documentation
+  - `.tx/`: Transifex configuration (not yet implemented)
+  - `img/`: Images used in the documentation
+  - `locale/`: Translations of the English documentation (not yet implemented)
+- `schema/`: schema-related files
+- `specs/`: TBD
+- `SteeringCommittee/`: Minutes of steering committee meetings
 
 The following files are created by running a build and are not version controlled:
 
-* `.ve/`: Python virtual environment (if using [python3-venv](#python3-venv))
-* `docs/_readthedocs`: Built HTML documentation
+- `.ve/`: Python virtual environment (if using [python3-venv](#python3-venv))
+- `docs/_readthedocs`: Built HTML documentation
 
 ### Sphinx
 
@@ -262,8 +257,8 @@ https://rdl-standard.readthedocs.io/en/latest redrirects to https://rdl-standard
 
 [Automation rules](https://docs.readthedocs.io/en/stable/automation-rules.html#automation-rules) are configured to:
 
-* Activate, build and hide a new version when a commit is pushed to a new branch in the GitHub repository.
-* Delete the associated version when a branch is deleted in the GitHub repository.
+- Activate, build and hide a new version when a commit is pushed to a new branch in the GitHub repository.
+- Delete the associated version when a branch is deleted in the GitHub repository.
 
 [Pull request builds](https://docs.readthedocs.io/en/stable/pull-requests.html) are also enabled.