Hello & welcome to Part 6! This section is about documentation, how to set up our documentation, and how to hows our documentation for free on the internet.

Build Some Docs

Documentation is super important! Good docs help people use and understand your software. This includes both readme files that help people get started, and detailed docs for each method.

We’re going to use a thing called Sphinx to generate our documentation from the comments we leave in our code. Sphinx is really complicated and powerful, but we’ll be using it in a pretty simple way.

cd into the doc folder, and take a look around. You’ll see a bunch of Sphinx boilerplate code. The exact code here is not something you should worry about! Instead, run make html – this will generate all your documentation for you, in _build/html.

Checkpoint

  • Open _build/html/index.html in a web browser.

You should see:

  • A working webpage!

Write Some Docs

Rad, so we know how to make our docs, this is great. But where do all those words come from?

It turns out that Sphinx reads from comments that are formatted in a certain way. This is cool because it means we can write good comments in our code, and have those comments automatically turn into our docs! Let’s make a branch (git checkout -b update-docs), and write some documentation.

Find a function called midi_to_hz in toymir/freq.py - you’ll see that it does not have any documentation. Take a look at hz_to_period - you’ll see that it has a detailed description of how it works, what parameters it takes, and what it returns.

Based on this example, add a docstring to midi_to_hz. Once you’re happy with your docs, run make html from the doc folder again, to generate your new docs!

Checkpoint

  • Open _build/html/api.html in a web browser.

You should see:

  • A working webpage, with your new docstring!

Read The Docs

So now our local documentation is updated. You are probably thinking that it is not much good to have local documentation – if only there were some way to put our documentation on the Internet in an easy way!

Lucky for us, there is a web service called ReadTheDocs that does exactly that. It works like Travis CI – when you merge new code to GitHub, ReadTheDocs will build and display your documentation for you. You can look at an example from one of our project here.

Due to a bunch of technical hoo-hoorah, ReadTheDocs won’t let each of you build your own version of the documentation for this module … but our original repository can. So, we’re going to combine this step with sending a pull request to our original repository, so you can see how ReadTheDocs works.

Those documentation changes you made are still unmerged. Commit your changes to your branch, and push it to GitHub. Make a pull request, but! When selecting what to make a pull request against, select bmcfee/ismir2018-oss-tutorial, rather than your-user-name/ismir2018-oss-tutorial. Then create the PR as normal from there.

(If you’re doing this tutorial later, you should take a look at our appendix for how to set up Read The Docs, so you can make your own docs!)

Checkpoint

  • You should see your PR on GitHub … and we’ll work through merging each one!

README and LICENSE

We’ve got formal documentation working, hooray! You should also look at two other files. README.md is your readme file – it’s the first thing that people see when they visit your project on GitHub.

In general, your README should provided an overview of your project, how to install it, and maybe give one or two very simple examples. The librosa README is a good example.

Finally, there’s LICENSE.md. It turns out that if you publish code to GitHub without an explicit license, it is not open source.

We highly recommend open source, and we highly recommend choosing an open-source license and applying it to your code. This is as simple as creating a file called LICENSE.md in your repository. You can take a look at https://choosealicense.com to help you pick one - we recommend the MIT license, ourselves.

GitHub will also probably ask you for things like a Code of Conduct, guidelines for contributors, issue templates, and so on. These are important, but are outside the scope of this tutorial!

Success!

We’ve added some documentation, and seen how ReadTheDocs can be used so that our docs will always be available on the Internet! We also talked about READMEs and licensing. In Part 7, we’ll talk about Jupyter notebooks, and take a tour of the Python MIR ecosystem.