Tutorials

This page contains tutorials to help you learn how to edit the standard.

Contribution workflow tutorial: edit, build, and test

This tutorial introduces the recommended workflow for standard development: automatically build the documentation each time you make a change, and run tests before comitting any changes.

! [IMPORTANT] Before beginning the tutorial, you need to set up your development environment using GitHub Codespaces.

Build the documentation, start a webserver and rebuild on changes

1. Using the terminal, change to the docs directory: cd docs
2. Build the documentation: make autobuild
3. Open the documentation in a new browser tab by ctrl+clicking on http://127.0.0.1:8000

   [sphinx-autobuild] Starting initial build
   [sphinx-autobuild] > python -m sphinx build -nW -q -b dirhtml -d _readthedocs/doctrees . _readthedocs/html
   [sphinx-autobuild] Serving on http://127.0.0.1:8000
   [sphinx-autobuild] Waiting to detect changes...

Edit a file

1. Open docs/index.md using the explorer view
2. Change the title on the first line of index.md using the editor and save your changes (Ctrl+S)
3. If your change breaks the build, you will see an error message. Otherwise, you'll see the following:

   [sphinx-autobuild] Detected changes (index.md)
   [sphinx-autobuild] Rebuilding...
   [sphinx-autobuild] > python -m sphinx build -nW -q -b dirhtml -d _readthedocs/doctrees . _readthedocs/html
   [sphinx-autobuild] Serving on http://127.0.0.1:8000
   

4. View your change in the built documentation by refreshing the tab in which the documentation is open

Run tests

1. Add a new terminal instance by selecting the + icon on the top-right of the terminal panel
2. Using the terminal, run the tests: pytest tests
3. Review the test results

   tests/test_csv.py .                                                                                                                 [ 16%]
   tests/test_json.py ...                                                                                                              [ 66%]
   tests/test_schema.py ..                                                                                                             [100%]
   
   ============================================================ 6 passed in 1.18s ============================================================
   

If the documentation builds successfully, you are happy with your change, and the tests pass, then you are ready to commit your change and push it to GitHub.