Documentation

[fluidnumerics-joe]

Hey all, I've started a branch (https://github.com/ROCmSoftwarePlatform/hipfort/tree/repo-docs) where we can start working together on building this repository's documentation.

• CONTRIBUTING.md
• SPECIFICATIONS.md
• readthedocs

It'd be great if we can be transparent in the specifications about the assumptions and expectations we have for end-users of hipfort and provide clear guidelines for revising hipfort specifications with the community.

To lower the barrier for community engagement for contributing to the hipfort repository, we should spend some time thinking about our branching model, versioning model, and process for moving branches from features and bug fixes and into develop and main branches. Documenting this and publishing to this repository will help users and potential contributors more easily see how we get work done on hipfort.

To start, here are some questions to spur discussion around contributing

• What are our acceptance criteria for getting branches into develop, main, or even into tagged releases ?
• How can we enable others to test their contributions before opening pull requests ?
• Do we want to automate testing ?
• What information is necessary when opening feature requests or bug reports ? Do we want to leverage issue templates ?

[domcharrier]

@schoonovernumerics I added a doxygen target to the sphinx Makefile.
Would be interested in using breathe to integrate this docu into the sphinx doc you added.
Do you have some experience with that?

[fluidnumerics-joe]

I have not used breathe before but will look into it. Thanks for setting this up. This is a good step in the right direction. From what I recall with Doxygen, we can annotate source code in comments to pull in additional information. I'm thinking that for a number of the functions, having example usage would be helpful. I'll pull down what you've started here and see what we can do to accompany the doxygen API documentation.

[domcharrier]

@schoonovernumerics , all modules are automatically generated from the C/C++ HIP and ROCm header files.
If there is any documentation in these files, it will be attached to the respective interface.

Interestingly, the roc* libaries, particularly rocsolver, provide more docu than the hip* ones.
Here is an example of rocsolver:

[domcharrier]

Each interface has a number of additional routines that internally call the _orig or _b routine, which is directly bound to a C function and takes type(c_ptr)
arguments. These additional routines, typically called _rank0, _rank1, full_rank, directly take Fortran pointers
with rank 0 (scalars), rank 1 (vectors) or full rank (a mix of matrix and vector arguments where appropriate.
We can certainly add some more docu to these routines that explains their respective suffix.

EDIT:

@schoonovernumerics Thanks for your suggestions regarding adding examples. It should not be that difficult to let some additional docu flow into the generated files.

[domcharrier]

@schoonovernumerics I am currently using Github Pages to host the doxygen docu associated with hipfort.

You can find the docu under the following address:
https://rocmsoftwareplatform.github.io/hipfort

README.md hipfort webpage URL both refer to this page now.

[fluidnumerics-joe]

Is there a way to bring in additional documentation to the github.io page, in addition to the API documentation from doxygen ? Things like, how to's and basic tutorials/demos.

[domcharrier]

Yes, it is possible. Github Pages just looks for a README.md or index.html at the specified location.
My plan would be to integrate the doxygen docu with the sphinx guide via breathe and
then point Github Pages to the sphinx guide's index.tml

[domcharrier]

We have to work a little on the guide first before this makes sense.