-
-
Notifications
You must be signed in to change notification settings - Fork 129
LFortran Season of Docs 2022 Case Study
Organization or Project: LFortran
Organization Description: LFortran is a modern open-source (BSD licensed) interactive Fortran compiler built on top of LLVM. It can execute user’s code interactively to allow exploratory work (much like Python, MATLAB or Julia) as well as compile to binaries with the goal to run user’s code on modern architectures such as multi-core CPUs and GPUs.
Authors: Ondřej Čertík, Rohit Goswami
Our goals were twofold. One was to create a readable and permissively licensed documentation of all Fortran intrinsic functions. Additionally we needed to setup documentation for LFortran’s internal representation (ASR).
In keeping with our objectives, we outlined the timeline and deliverables for generating documentation for the Fortran intrinsics as well as for the ASR.
Compilers need to document the implementation details of a programming language standard. The unique design of LFortran's internals mean that this section of our documentation can be reused by the various other front end libraries. We have created the proposal publicly on a wiki page and asked for feedback.
We have budgeted $5,000 per project, we had two projects (documenting the intrinsic functions and documenting our internal representation). So far we have spent $2,000 on each project. We intend to spend the other $3,000 per project ($6,000 total) when we receive the remaining funds.
The person who worked on the project: Tapasweni Pathak
We announced publicly on Twitter, Fortran-lang discourse, mailinglist and Zulip that we were looking for a technical writer. We evaluated applicants and selected Tapasweni as the best candidate.
The timeline was to deliver on both projects by the end of November 2022.
We have documented both the intrinsic functions and the internal representation, and the documentation is available at: https://docs.lfortran.org/ The project also resulted in general improvements to our documentation, such as providing translations, and streamlining how documentation should be provided.
We will consider the following metrics for success:
- Documentation framework and styleguide
- Roughly 50 intrinsic functions
- Language design internals
- ASR documentation
We have succeeded on all four, we now have a documentation framework, and most of the intrinsic functions are documented. We have documentation on the language design internals as well as ASR documentation.
What went well was to use Markdown as the documentation medium, as it allows us to choose later how things are formatted. We started with MkDocs, then moved to Sphinx as we had a contributor who set up translations using Weblate for us using it.
For the internal representation, that we call the Abstract Semantic Representation (ASR), the documentation effort was especially helpful, as we started with having the ASR node definitions in a file with short comments, but it was hard to remember what each argument is supposed to do. After working on the documentation, we now have a nice system of one Markdown per ASR node, with sections such as Syntax, Arguments, Description, Types, Examples and See Also, which allows to thoroughly document each ASR node, with examples where and how it would be used. When adding a new node, we now try to create a documentation Markdown file for it explaining all the details how it should be used.
Overall, we have studied how other good well regarded documentation projects are structured and what sections they use and we tried to follow a similar approach. We now have a nice working and current documentation, as well as a very solid foundation for future work.
We have documented the intrinsic functions in Fortran and our internal intermediate representation. We have worked with Tapasweni to design how the documentation should look like, what sections it should have, examples how each section should look like, the overall structure of documentation, and then we worked with her on reviewing individual contributions.
As a result, we now have Fortran intrinsic functions documentation, as well as Abstract Semantic Representation (ASR) documentation, and in addition we also have the process streamlined, so that the LFortran developers as well as the wider community can keep contributing more documentation.
We are very excited about the results and are looking forward to further improving them. It has been a very nice experience working with a technical writer to create high quality documentation. Thank you Google for supporting this work.
The advice to other projects would be to think about the documentation and setup good infrastructure that the whole community can contribute to.
We would like to thank Tapasweni Pathak for working hard as the technical writer for LFortran. We thank Google for supporting this work. We thank MkDocs and Sphinx authors for creating great documentation generators. We thank Sebastian Ehlert for setting up translations in Sphinx and Weblate. We want to thank all LFortran developers and the wider community for supporting this work.