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.

Create a branch for your changes

1. Create a branch using VS Code, or via the terminal:

   git branch tutorial-branch
   git checkout tutorial-branch

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. If you only changed the title of docs/index.md, the test should pass:

   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 changes, and the tests pass, then you are ready to commit your changes.

Commit your changes

1. Stage your changes using VS Code, or via the terminal:

   git add docs/index.md

2. Commit your changes using VS Code, or via the terminal:

   git commit -m "docs/index.md: Update title"

Wrap up

If you were editing the standard 'for real', the next steps would be to push your changes to GitHub and create a pull request to merge them in to the current staging branch. However, since this is a tutorial, you can delete your branch and delete your codespace.