2.1. About the Lectures

Because these course notes will be a collaborative effort, they will be updated essentially in real-time. There are a few ways to access the notes:

  • The main way is via the external-facing web-page which will contain changes and contributions approved and merged by the instructor or the TA

  • The source code which can be accessed from the course notes Github repository. This will allow you to build your own local html or pdf version of the notes (see below)

2.1.1. Building a static version of the notes

The course notes are built using Sphinx, a Python-based tool for creating documentation.

Sphinx allows you to easily build a HTML or PDF version of the notes (the PDF is created via LaTeX).

To build either the HTML or PDF notes, you will need to clone the repository and change to the docs directory:

git clone https://github.com/uoguelph-engg3130/coursenotes.git
cd docs

To build HTML use the Makefile as follows:

make html

This will create a site in the subdirectory _build/html. To build a PDF, you will first need to set up LaTeX on your computer and ensure that you can run pdflatex. Then use the Makefile as follows:

make latexpdf

This will output the latex code and compiled pdf in _build/latexpdf.

2.1.2. Contributing to the course notes

Every student is expected to contribute to the development and maintenance of these course notes. In fact, your contribution is worth 10% of the final grade!

Students will be assessed on the quantity and quality of the contributions, which may include:

  • Being the primary note taker for one lecture session

  • Correcting errors or making additions to existing notes (or labs, etc.)

  • Opening issues and participating in discussion where more clarification is needed

  • Responding to these issues

Contributions must be submitted as a Github pull request. The instructor or TA may provide feedback and request changes or additional contributions prior to merging. We will be using the fork and pull model.

2.1.2.1. Sphinx

In order to contribute to the course notes, you will need to familiarize yourself a bit with:

The Restructured Text and Sphinx CheatSheet is a great overview. The Sphinx documentation also has a good reStructuredText Primer.

2.1.2.2. Recipe

The general recipe for contributing to the course notes is as follows (note that this essentially follows these notes ):

  1. Fork the engg3130/coursenotes repository via Github

  2. Clone your fork to your computer

  3. Make some changes (you may wish to do this in a topic branch)

  • For example, you may modify a particular lecture e.g. docs/lectures/lectureXX.rst

  1. Build the HTML version of the notes (as per the instructions above) and view the changes in the _build/html directory. Make sure that the build runs without warnings or errors and that you are happy with the HTML

  2. Commit these changes

  3. Review the the Checklist below

  4. Push these changes to your fork

  5. Create a pull request which proposes your changes into the main project; make sure you include an informative message with your request

  6. Wait for feedback or notification that your pull request has been merged

Note that to make further changes, you won’t need to re-clone the whole repo. Just make sure you pull any new changes into your repository, so that you are working on the most recent version of the code. Then you can repeat from step 3 above.

2.1.2.3. Checklist

Before submitting a pull request, please review this list of common issues. This will minimize the amount of back-and-forth with the TA, and ensure that your changes are merged in as quickly as possible. If you have any questions or doubts about the following, don’t hesitate to ask the TA for help.

  1. Did you leave in the includes at the beginning of each lecture? The lecture notes should still start with “Before this class…” “Before next class…”. Start your content after that.

  2. Did you add your name as note taker?

  3. Did you use hard line wrapping at 80 characters?

  4. Did you give proper attribution for any third-party resources used?

  5. Did you avoid any .gif images (in favour of .pdf or .png)?

  6. Did you use restructured text’s embedded math for any math notation (e.g. squares and cubes, math operators like log, variable names, equations, etc.)

  7. Do the levels of your headings match the rest of the notes?

  8. Did you avoid the use of any extra formatting (bold, italic, etc.) in your headings?

  9. Did you run a spell-checker on your notes?

  10. Did you commit any dependencies (images, etc.) to your repository?

  11. Did you avoid checking in any temporary files?

  12. Have you eliminated all errors and warnings when you build the HTML?