The appication form for GSod 2022 can be found here.

HPX's existing documentation can be found here. While it's already quite extensive, it has grown organically and needs restructuring and heavy editing. We recently moved our documentation to Sphinx for better navigation, but the content remained mostly unchanged. One problem is that the documentation contains a lot of information, which means that beginners can often struggle to find what they're looking for. At the same time, we don't want more advanced users to feel like they can't find what they're looking for.

The HPX documentation is written using reStructuredText and rendered using Sphinx. Familiarity with these is helpful but not required as reStructuredText is easy to pick up. In addition, since HPX is mostly implemented in C++, at least a basic level of familiarity with C++ will be helpful in understanding code examples and concepts explained in the documentation.

Project scope

The aim of the project is to:

• Write from scratch new example use cases of HPX and provide code snippets for two cases:

  1. Full representative examples that utilize major HPX functionalities and users will be able to trace and compose in order to use HPX. Last year we developed a matric multiplication example. This can be extended to beginner, intermediate and advanced usage examples for the users to be able to access a narrow tutorial-like series of examples.
  2. Minimal use cases (5-10 liners) that showcase the usage of core API utilities. These are different kind of examples since they will utilize isolated parts of HPX without composing them into a greater script that would do complicated work. It would rather demonstrate essential usage of simple functionality.

  Various examples already do exist throughout our documentation. The writer will have the option to collect them and provide a uniform web interface for the users to access them.

• Expand on the API documentation and work towards ephasizing and unifying the C++ Standard conformance of HPX. Beyond decoupling and improving the aesthetics of our API, we would like to provide further linkage on corresponding C++ Standard facilities that are implemented in HPX.

• Create a "design document" containing guidelines for how to add new content to the documentation: tips on how to structure new sections, general guidelines on what sort of content should be presented in what chapters, etc.

The scope of the project is flexible as it can easily be divided into sub-projects, each focusing on a particular chapter or section. However, considering the time to get started and acquainted with the project, and leaving enough time for the project to have a significant impact we estimate 3 months of work.

Projects

Document standard facilities

• Abstract: HPX is largely modeled on existing or proposed C++ standard library functionality. While it's often enough to point users to standard library documentation (e.g., cppreference) as the HPX implementations usually follow the standard, it makes for a less than ideal experience for users as they have to jump between two different sites to learn about the HPX APIs. In some cases, the HPX APIs extend the standard facilities, and the standard documentation is not sufficient for users. This project aims to document such functionality within HPX for easier access for users. Examples of such un- or underdocumented features are future, async, tuple, optional, any. Presenting our API documentation in a better way can be combined with this project.
• Deliverable: New and/or corrected documentation for facilities corresponding to standard facilities.
• Mentors: Hartmut Kaiser (), Giannis Gonidelis (gonidelis[at]hotmail.com), Parsa Amini ()

Present API in a more structured and user-friendly way

• Abstract: As part of the move to Sphinx as a documentation system, the quality of presentation of our API documentation was reduced. As we're also planning a new major release of HPX and intend to specify the public API, a more curated presentation of the API may be a better experience for users. This project aims to take our current API documentation and present it in a more user-friendly way, either through the existing tools (Doxygen and Sphinx), through Sphinx extensions (Breathe), or tools completely outside of Sphinx (standalone Doxygen). The current API documentation is presented here in a largely unstructured way.
• Deliverable: Restructured API documentation.
• Mentors: Hartmut Kaiser (), Giannis Gonidelis (gonidelis[at]hotmail.com), Parsa Amini ()

Write tutorials based on existing tutorials presentation material

• Abstract: There are several HPX tutorials (e.g., HPX Workshop at HLRS - 2019) that implement example applications that are useful beginners. Some of these examples (e.g., Fibonacci, 1D Stencil) are included in the HPX documentation, and some are not. The objective of this project is to add these tutorials to the HPX documentation.
• Deliverable: New tutorials in HPX documentation based on existing code and other presentation material
• Mentors: Hartmut Kaiser (), Giannis Gonidelis (gonidelis[at]hotmail.com), Parsa Amini ()

Extend contributor's guide and consolidate content from wiki

• Abstract: We always appreciate volunteer contributions to HPX but think that the process could be made easier to encourage new contributors. Our contributor's guide should be as straightforward as possible and contain the necessary steps for a new contributor to go from building to testing and submitting a pull request. Currently, there is only a minimal amount of information in the "Developer documentation" section of our documentation. In addition, there is scattered information for contributors in this wiki.
• Deliverable: A new contributor's guide in our documentation to consolidates the existing information in the documentation and this wiki and expands it if needed with missing information.
• Mentors: Hartmut Kaiser (), Giannis Gonidelis (gonidelis[at]hotmail.com), Parsa Amini ()

Restructure headings within the current documentation

• Abstract: The HPX documentation currently contains headers that can be re-organized to enable quicker lookup and generate more intuitive documentation. Consider, for instance, comprehensive build instructions for HPX are found hidden under the manual header. While basic build instructions exist under quick start, a better alternative would be to have a "build instructions" header that takes you through the quick install and a step-by-step guide for cases when the former method throws CMake or compiler errors. The project aims at improving the visibility of certain headers through re-organizations.
• Deliverable: Restructured documentation layout with more intuitive headers and general sentence improvements.
• Mentors: Hartmut Kaiser (), Giannis Gonidelis (gonidelis[at]hotmail.com), Nikunj Gupta ([email protected])