GSoD Progress Documentation

This wiki is to share the progress of the GSoD project, includes weekly updates and tracking of the progress report. Would be updated on a weekly basis.

---

Project overview

The STE||AR has extensive documentation existing for its project HPX.

HPX is a C++ Standard Library for Concurrency and Parallelism. It implements all of the corresponding facilities as defined by the C++ Standard. Additionally, in HPX we implement functionalities proposed as part of the ongoing C++ standardization process. We also extend the C++ Standard APIs to the distributed case. HPX is developed by the STE||AR group (see People).

The goal of HPX is to create a high-quality, freely available, open-source implementation of a new programming model for conventional systems, such as classic Linux-based Beowulf clusters or multi-socket highly parallel SMP nodes. At the same time, we want to have a very modular and well-designed runtime system architecture that would allow us to port our implementation onto new computer system architectures. We want to use real-world applications to drive the development of the runtime system, coining out required functionalities and converging onto a stable API that will provide a smooth migration path for developers.

GSoD team

Writer - Rachitt Shah
Mentors - Mikael Simberg, Hartmut Kaiser.

Weekly Progress report - Month One

The team currently identified API Documentation as the first actionable task that needed fixing.
Here's why was this identified -

1. Currently, the indentation style is improper and less readable for users.
2. Users have trouble identify codeblocks and need to go over the complete documentation. The search function is also broken in some cases for APIs, which leads to users spending more time looking for documentation than learning/solving their queries on the platform.
3. The current theme was identified as a possible reason and is currently being fixed upon by the HPX docs team.

Week One

Writer on-boarding and formalities for the hiring were executed. This week involved lesser activity, being the first week of the documentation period.

Week two

The documentation team and the writer has their first standup. The agenda includes a proposed roadmap and feature identification. API documentation was given the highest preference according to the HPX team, and it was agreed to work on API documentation.

Week three

The docs team and the writer performed the installation of a couple of themes for the Sphinx platform. Included testing 2 themes, with more being tested alongside for getting better results for the docs.

Week four

Ongoing with the API themes for Sphinx documentation. The docs team also increased the frequency of the meeting, so as to improve the efficiency of the process. The team also floated a feedback form for our users to give the team an idea of where should we improve from an end-user point of view. This would be the agenda for the coming weeks, alongside fixing the APIs which carry higher importance. Also proposed was to improve the Windows OS installation documentation, however, it has lower priority than overall documentation improvement.

Week Five

The docs team was showcased 3 Proof of Concepts for the new API themes as decided in the prior weeks(three and four). Attaching each sample below, and the pros and cons of each theme.

Insegel
Homepage
API examples

The team wanted to work on AstroPy's theme and would be working on fixing the APIs docs on these themes for this week.

Week Seven

This week was largely involved with bettering and testing newer themes, and playing with Insegel's CSS. Insegel's CSS didn't respond as well as expected, however there have been several promising new themes that could be a good addition. Exhale themes were tried out as well,alongside the research on how can doxygen be improved, mostly by looking at examples.

Week Eight

Week eight was a non productive week with the team deciding the writer to spend more time with the product and build a strong conviction about building the project.

Week Nine

The complete week was spent in revisiting the documentation and here are some proposed ideas, alongside the need for scaling up PRs.

Contributing to HPX
Building HPX documentation
Building HPX on Windows, shifting build instructions from Manual to User Documentation.
Writing test cases for Windows
Create FAQ section for installation(mainly for windows)
Structure the Terminology page to make it more inviting/readable.
Add more details to troubleshooting, we if have errors.
Starting to work on a design document that would define the language of how should the docs be added.
Move things from Build instructions into a newer page.

Week Ten

Had 3 proof of concepts for doxygen and one theme for sphinx, with the graphic updation moving fast, the team hopes to work on the content agreement if everyone agrees upon the look of the theme.

Works in progress are a design document and the content agreement, which are the core of the project, and the writer would be picking this up.

Week Eleven

Work in progress, would update later

Insegel deployment - http://stellar.cct.lsu.edu/files/docs/exhale/insegel/html/index.html
Doxygen awesome deployment - http://stellar.cct.lsu.edu/files/docs/doxygen/doxygen-awesome/doxygen_awesome_hpx/html/

The week was mainly focused on getting the writer up to speed with things, alongside working on conf.py.in for working on a mix build of sphinx and doxygen

Week Twelve

A working and clean doxygen build were created, the only changes remaining were the addition of a new readme for the doxygen build, and testing the build with a sphinx build in a hybrid combiantion. On the content side, a draft PR was made for the build instruction.

Feedback

The team also conducts feedback sessions from the users, and is looking to expand the time investmemt in this area for further fine-tuning of the docs.