-
-
Notifications
You must be signed in to change notification settings - Fork 438
GSoD 2022 Project Report
Organization Description: The goal of the STE||AR Group is to promote the development of scalable parallel applications by providing a community for ideas, a framework for collaboration, and a platform for communicating these concepts to the broader community.
HPX’s previous GSoD projects were focused on presenting the documentation in a user-friendly way. Now that the documentation is much more presentable, HPX decided to focus on documentation content this year. HPX has hundreds of algorithms and classes. A lot of these elements had outdated or no documentation at all.
This issue of outdated documentation was exacerbated by the fact that Doxygen doesn’t fully support a lot of modern C++ directives and concepts like tag_invoke. These are used extensively by HPX. Since Doxygen doesn’t fully support them, class and function declarations need to be duplicated. These duplicated declarations also need to be synchronized with actual code whenever there is a change.
The main objective of the project was to improve documentation content by documenting currently undocumented elements, fixing outdated documentation and removing obscure documentation. We also planned to improve the build system and contiguous integration for the documentation.
The full proposal is available here: GSoD 2022 Project Proposal.
Having participated in Season of Docs in 2019 and 2021 we already had a preliminary list of potential topics for this year's Season of Docs. The basic idea was to make our documentation more accessible to the users. Google Summer of Code students were the best source of feedback for that cause. Based on feedback we hear frequently from them we decided to focus on the content that is already available in the documentation. We combined the most critical parts from a few project ideas from 2019 and 2021 into one project. For example, a commonly recurring difficulty for new Summer of Code students is how to build HPX.
While we did find a potential technical writer during the application period, we still decided to leave the project proposal relatively open to fit various experience levels, so that we could adapt the topic to the hired writer and the requirements as revealed by talking to our users.
The budget, like the project scope, was left relatively open to be able to adapt to the experience level of the technical writer that we hired. We estimated a rough budget based on average technical writer salaries and a 3-to-5-month project of part-time work. This had worked very well for us in the previous GSoD projects. We knew ahead of time that there would likely be enough work in our documentation for far longer than a 5-month period and thus the project would have to focus on only a subset of the documentation. Likewise, if the writer would make faster than expected progress, we knew there would be enough work for them towards the end of the project. Based on this we estimated a budget of USD 5000.
At the time of writing the case study we have paid out the full 40% (USD 2000) given at the beginning of the project to our selected technical writer. The remaining 60% of the budget is left for ongoing and potential future work by the current technical writer. All in all, we spent (or rather allocated) the budget in a pace conforming to the plans as to the project did go forward at a nice progress. We intend to pay out the remaining grant soon after the official end of the project. We are also planning to transfer some additional external funds to our Open Collective account that we intend to use for similar projects in the future.
The core Season of Docs team consisted of:
- Technical writer: Bhumit Attarde
- Support and mentoring: Ioannis Gonidelis, Hartmut Kaiser, Dimitra Karatza
We had one technical writer during the course of the project: Bhumit Attarde. We are very happy with Bhumit's work and hope that he will decide to stay with the project to help further improving the documentation in the future.
We advertised the acceptance of HPX to Season of Docs on our blog. We asked writers to fill in a simple application form. Although the official project proposal was already written by us, we asked writers to include which parts of the proposal they would like to focus on, both in terms of interest and previous experience. Additionally, we asked writers for a brief overview of their background, and motivation to work on HPX in general and specifically as a writer for our documentation.
We hired our technical writer at the beginning of the project. We set up weekly calls with the technical writer, just like previous runs of Season of Docs and Summer of Code. This has been essential in keeping track of progress and making sure things are going in the right direction. Additionally, quick questions were typically handled on IRC, and more in-depth questions were handled either in the weekly calls, via email, or on GitHub issues. With the core team already spread out across the US and Europe, we are already used to the mostly asynchronous forms of communication. We found that the technical writer adapted quickly to this setting.
The writer was supported by two core HPX developers: Hartmut Kaiser and Ioannis Gonidelis. Dimitra Karatza is a member of our team since GSoD 2021 (she has decided to keep working on our documentation beyond last year's project) has helped with issues and ideas related to this year's documentation work as well.
The project had the following timeline:
- June: Debugging and repairing broken Public API links and partially documenting parallel algorithms.
- July: Continuing to document parallel algorithms, fixing function signature discrepancies with the C++ standard, updating meta documentation and CI system.
- August: Continuing to document parallel algorithms.
- September: Documenting various headers like
condition_variable,mutexand adding missing links to the public API page. - October: Adding CPPReference named requirements support, fixing documentation build system and removing leftover section of build script, updating Doxygen config to make the documentation cleaner, documenting remaining headers like
semaphore.
It should be noted that we were able to significantly improve the build system, find documentation as well as implementation related discrepancies between the C++ standard API and HPX even though it wasn’t planned or included in the proposal.
The changes made during the project are listed below with links to the corresponding pull requests.
| Pull request(s) | Documentation pages (if any) |
|---|---|
| https://github.com/STEllAR-GROUP/hpx/pull/5915 | https://hpx-docs.stellar-group.org/branches/master/html/api/public_api.html |
| Pull request(s) | Documentation pages (if any) |
|---|---|
| https://github.com/STEllAR-GROUP/hpx/pull/5954 | |
| https://github.com/STEllAR-GROUP/hpx/issues/6008 |
| Pull request(s) | Documentation pages (if any) |
|---|---|
| https://github.com/STEllAR-GROUP/hpx/pull/6007 | https://hpx-docs.stellar-group.org/branches/master/html/api/public_api.html#hpx-condition-variable-hpp |
| | https://github.com/STEllAR-GROUP/hpx/pull/6012 | https://hpx-docs.stellar-group.org/branches/master/html/api/public_api.html#hpx-mutex-hpp |
- HPX Resource Guide
- HPX Source Code Structure and Coding Standards
- Improvement of the HPX core runtime
- How to Get Involved in Developing HPX
- How to Report Bugs in HPX
- Known issues in HPX V1.0.0
- HPX continuous integration build configurations
- How to run HPX on various Cluster environments
- Google Summer of Code
- Google Season of Documentation
- Documentation Projects
- Planning and coordination