Summer OSPP with CHAOSS — Week 3 & 4

It’s been one month since I started my work on revamping the GrimoireLab tutorial and it’s been going pretty well. My mentors and I have been meeting on every Friday to discuss the ongoing progress and future plans.

Week 3

The previous week, I was told to look into a way to document the source code of SortingHat and I went with Sphinx.

Sphinx did a great job at documenting every single module in SortingHat. It even displayed the modules in a proper and appealing way. There were a few warnings though when building up the documentation and that caused part of the documentation to be missing. I spent a few days adding the necessary configs, building the docs and hoping for the number of warnings to decrease.

There was around 38 warning in the beginning and It got reduces to 3 warnings. The current warnings do not affect the generation of the docs in any way and are present by choice.

Week 4

This week, we decided to move on to the deployment of the documentation as it was mostly ready. After our meeting on Friday, we decided to try out Github Pages to host the documentation. It worked properly but we needed an additional branch on the SortingHat repo to get it working. Since that was not an option, we moved on to ReadTheDocs.

We decided on ReadTheDocs for two reasons:

1. We found out that Sphinx and ReadTheDocs work well together from our previous research and the existing perceval documentation confirmed it.
2. ReadTheDocs automatically rebuilds the documentation if any changes is ported to the connected repo through a webhook. We do not need to define a workflow and maintain it.

You can find the sample doc here.

Conclusion

The past two weeks have been great !

The best thing about the past two weeks was the merging of my PR’s into the SortingHat codebase. For now, the documentation configuration files and some initial docs were merged. The main documentation about the use of SortingHat’s new interface is quite large and needs to be seperated into different PR for a better review.

So hopefully by the end of this week, everything will be merged !