I continue working on Open Web Calendar after I resolved an issue to deprecate Python 3.9. This time, I try to work on another type of issue that I've never done before - optimization of documentation build for testing.
About the issue
The issue is to add a quick documentation build for testing, by introducing a MkDocs configuration file (mkdocs.test.yml) that inherits from the main mkdocs.yml. Using this configuration file, documentations should be built in only English and one more well-translated language using MkDocs, unlike building documentations in full set of languages as specified in mkdocs.yml. The quick documentation build should be incorporated in a new tox test, which will be integrated into GitHub Action specified in run-tests.yml.
The progress of problem solving
As I have not handled similar issues before, I didn't know how much time I would spend on this issue, but I wanted to let the maintainer and the community know that I was working on the issue and show my progress. This was the perfect scenario to create a draft pull request, to allow the community to check my work in progress while preventing accidental merges. I made the draft pull request after pushing the mkdocs.test.yml file, indicating the work done and to be done, as shown in the image below.
The remaining work was to update tox.ini and .github/workflows/run-test.yml for the new documentation build as suggested by the maintainer in the issue. Given my limited knowledge to tox and Github workflow, I had to do some research on how to change the files. I also found it useful to make reference to existing codes, not only could I make my codes more consistent, the codes also provided templates and comments that indicate the subtle details I should beware of. Making reference to existing codes while researching along the way, I was able to add the refined documentation build to tox.ini and run-test.yml.
Errors often pop up in the progress of solving an issue, this time is no exception. The first error I encountered was the failure to build the documentations with the new tox command, but thanks to the detailed logging from tox, I was able to locate the incompatible dependency that blocks the build, and fix it accordingly. Everything seemed to run well, I pushed my codes and they passed the check by GitHub Actions, including the new documentation build test I added in run-tests.yml, but something was still bugging me...
The documentation build I added was way quicker than the original build, the full documentation build for all languages (30+) took 24 mins, but my new documentation build for 2 languages only took around 10 seconds, which was disproportionate, and the pages were not properly translated. The tox command and GitHub Action worked fine, so I suspected that the mkdocs.test.yml, which I created at the beginning, was the source of problem.
Luckily, I got a hint from the maintainer, who provided a link about configuration inheritance in the issue he posted. It turned out that I had to use the key/value pair syntax for the plugins option in both parent and child configuration file, in order to override the values, which were the language list in this case. I thereby made changes to both mkdocs.test.yml and mkdocs.yml, tested the new documentation build in local machine, and got the translated pages in 2 ~ 3 mins build time, which was proportional to the original build.
Eventually, I pushed all my changes, passed the GitHub Actions check, edited the summary of changes, and changed my pull request to "ready for review" for the maintainer's acceptance.
Lessons learnt
First of all, I have learnt the importance of making the work transparent to the open source community, even if the work is still in progress. This prevent the case of different people working on the same issue redundantly, while allowing others to know the progress and check the work in case things go wrong.
Moreover, I realized that there was no single best way to find solutions. We often have to find different sources, such as the official documentation, existing code references, and discussion on forum, to cross-check the finding and validate the solutions, as the answers from different sources may be different and sometimes mistaken.
After working on this and my last issue on Open Web Calendar, I have known more about the file structure, general workflow, and maintenance work of open source projects, and gained confidence in solving unfamiliar issues while acquiring new set of knowledge in the future. Looking forward to solving new issues in the next few weeks!
Top comments (2)
Really like how you documented your process and used a draft PR to keep the work transparent. It's a thoughtful approach, especially when you're exploring new ground with tox and GitHub Actions. Looking forward to seeing how the optimization turns out and what else you learn along the way.
Thanks for your comment! The blog has been updated. Now I've pushed all my codes and waiting for the maintainer's acceptance/comments.