Contributing to test-doc-pack

Contributing to test-doc-pack#

Firstly, thanks for thinking of contributing to test-doc-pack. You can help out by submitting issues (when you encounter bugs, typos, inconsistent information, etc.) or by adding to the content here. To know how to get started with content development, jump to Development Workflow. This book is also compiled with Jupyterbook and helped by the Teachbooks template. You will find additional resources there to help with development details particular to those environments.

If you want to contribute, but don’t know where to start, you can also have a look at the issues and you will find where test-doc-pack needs help. Pick an issue and assign it to yourself, so others know that you are working on that. If you are not sure how to proceed, you can express your interest by commenting on the issue, and someone should help you out.

Development Workflow#

  1. Fork & clone test-doc-pack

    Fork the test-doc-pack repository.

    Clone your fork and set the original repository to remote upstream with the following commands:

    git clone git@github.com:<your-github-username>/test-doc-pack.git
cd test-doc-pack
git remote add upstream git@github.com:Geet-George/test-doc-pack.git

  2. Create a branch

    Now we have a local copy of our fork and we can start developing.

    It is always good coding practice to work on a different branch every time you start working on a new feature / bug-fix (yes, despite having your own fork).

    Create a branch and checkout to start working on it.

    git branch my-new-feature
git checkout my-new-feature

    Alternatively, do it all in one line.

    git checkout -b my-new-feature

    Note that regardless of which branch you are on currently, you can still specify off which branch you want to create a new branch by (shown here as branch off main):

    git branch my-new-feature main

  3. Make your changes

    Do your edits and push to your fork. Behold git’s holy trinity!

    git add . # will add all uncommitted changes
git commit -m "your commit message here" # consider giving a detailed message & not simply a header
git push # for the first push of a branch, track it e.g. git push -u origin my-new-feature

    Every commit makes changes that are justified by one reason. The size of a commit could be a single character change or a change in thousands of lines across millions of files. But the reason behind the commit should ideally be as solitary as possible. Commit often, but not too often. I think Henry VIII might have said that.

    Building the book locally

    Caveats for Quarto Slide Decks
    1. Ensure that the `_quarto.yml` file has the following config lines: 
           project:
       output-dir: "."
    2. Include the following `revealjs` configs in the `_metadata.yml` for the slide decks to work properly with Jupyterbook. 
           format:
         revealjs:
             self-contained: true
    3. Build the slides using Quarto first before running teachbooks build. Do this with quarto render /path/to/slides.qmd. The output-dir specified in the _quarto.yml should ensure that the HTML is rendered in the correct location for Jupyterbook (teachbooks) to be able to find it.
    4. If this is a new slide deck you created, make sure to add it to the slides_index.md file so that it gets included in the book. For example, if the slide-deck is titled lecture1_slides.qmd, add the following: <a href="slides/lecture1_slides.html">Lecture-1 Slides</a>
    5. Note that the current setup is to locally render the slides using Quarto, build the webpage (book) using Jupyterbook (teachbooks build), and finally add the HTML output to the repository (don't forget this last bit!). Only then will the rendered slides show up on the webpage. The Quarto rendering does not happen as part of the CI/CD pipeline. It would be great though to include this as part of the CI/CD pipeline some day.

    If you'd like to see how the changes you've made in the documentation look, you can build the book locally. You can do this by running the following command in the terminal: 
    teachbooks build book/

    Be sure that you have the teachbooks package installed. If not, you can install it by running:

    pip install teachbooks

    You can then view the book by opening the book/_build/html/index.html file in your browser. Sometimes, you might need to clear the cache of your browser to see the changes or run the build command again. Also, note that if you have created a new file, you will need to add it to the book/_toc.yml file to see it rendered on the website.

  4. Submit pull request

    Head over to Github and from the relevant branch in your fork, create a Pull Request (PR).

    You can request a PR review from someone. They will help with some feedback or might wholeheartedly agree with your changes. Others might also comment with their opinion. Add any necessary changes with subsequent commits to the same branch. Once everyone involved in this conversation is satisfied, the PR is merged. From personal experience though, frantically refreshing the browser every three seconds doesn’t speed up the response rate of others. Sometimes, PRs can just take their own sweet time.

  5. Checking deployment

    For the latest commit in your PR, you’ll find that Github starts running some Actions to deploy these changes. If successful, you’ll see green ticks. These changes are still not however to the main webpage. These are deployed to a “branch” of the webpage, which you can access at https://geet-george.github.io/test-doc-pack/<your-branch-name>.

  6. … And that’s it! Thanks for helping

P.S. If something here doesn’t work, or you have suggestions to improve this guide, feel free to submit an issue or PR. :)

Contents