MODERN DOCUMENTATION ACROSS LANGUAGES ROHIT GOSWAMI Created: 2021-07-16 Fri 19:08 1

BRIEF INTRODUCTION 3

HELLO! Find me here: Who? Rohit Goswami MInstP Doctoral Researcher, University of Iceland, Faculty of Physical Sciences https://rgoswami.me 4

LOGISTICS All contents are Slides are in presentations/SERI2021 hosted on GitHub Questions are welcome after the talk 5

THE RATIONALE 7

READING CODE I main: push rbp mov rbp, rsp mov DWORD PTR [rbp-4], 3 mov eax, 0 pop rbp ret __static_initialization_ and_destruction_0(int, int): push rbp mov rbp, rsp sub rsp, 16 mov DWORD PTR [rbp-4], edi mov DWORD PTR [rbp-8], esi cmp DWORD PTR [rbp-4], 1 jne .L5 cmp DWORD PTR [rbp-8], 65535 jne .L5 mov edi, OFFSET FLAT:_ZStL8 __ioinit call std::ios_base::Init::Init() [complete object constructor] mov edx, OFFSET FLAT:__dso_handle mov esi, OFFSET FLAT:_ZStL8__ioini mov edi, OFFSET FLAT:_ZNSt8ios_bas call __cxa_atexit .L5: nop leave ret _GLOBAL__sub_I_main: push rbp mov rbp, rsp mov esi, 65535 mov edi, 1 call __static_initialization_ and_destruction_0(int, int) pop rbp ret But who writes assembly anyway? 8

READING CODE II int main () { int D.48918; { int a; a = 3; D.48918 = 0; return D.48918; } D.48918 = 0; return D.48918; } void _GLOBAL__sub_I_main.cpp () { __static_initialization_ and_destruction_0 (1, 65535); } void __static_initialization_ and_destruction_0 (int __initialize_p, int __priority) { if (__initialize_p == 1) goto ; : if (__priority == 65535) goto ; : std::ios_base::Init::Init (&__ioinit __cxxabiv1::__cxa_atexit (__dt_comp &__ioinit, &__dso_han goto ; : : goto ; : : } GIMPLE is an internal gcc representation… 9

READING CODE III #include int main() { int a=3; return 0; } Better for most people, still a bit lacking for novices Assigning an integer Produces a file binary which can be run as: Output There is no output, but an assignment of an integer with value 3 takes place g++ main.cpp -o file ./file What about different languages? 10

READING CODE IV Maybe gcc is just an ugly compiler… program main integer :: x = 3 + 6 print *, x end program lfortran has a nicer intermediate structure conda create -n lf conda activate lf conda install lfortran \ -c conda-forge lfortran --show-asr consint.f90 11

PROJECT LAYOUTS 13

LANGUAGE AGNOSTIC BEGINNINGS Readme.{md,org} Motivation, rationale, license, installation instructions LICENSE Plain text, and preferably an open license is pretty handy for this license-generator .gitignore Lists files which do not need to be committed; typically generated files can be used to generate these gibo $ git init # Inside project $ gibo macOS Windows Xcode Emacs \ Vim Python C++ \ CMake TeX > .gitignore $ touch readme.md $ license-generator MIT \ --author "Person" $ tree -L 2 . ├── LICENSE ├── docs │ └── pres └── readme.org 2 directories, 2 files 14

LARGE PROJECT STRUCTURE Has a core With bindings For other languages Needs api documentation Also user documentation . ├── api-docs ├── dependencies ├── python-symengine-feedstock ├── symengine ├── symengine-bench ├── SymEngineBuilder ├── symengine.f90 ├── symengine-feedstock ├── symengine.github.io ├── symengine.hs ├── SymEngine.jl ├── symengine-paper ├── symengine.py ├── symengine.R ├── symengine.rb ├── symengine.spkg └── symengine-wheels 15

DOCUMENTATION DISSEMINATION 17

MAN PAGES Great for terminal programs Not great for APIs 18

USER MANUALS Can be hard to manipulate C++ standard is ≈1800 pages 19

WEBSITES How many? Must provide metadata about the code Community building aspects

20

DOCUMENTATION INSERTION POINTS 22

USER PERSPECTIVE Tutorials Code-along 23

DEVELOPER PERSPECTIVE API documentation Code contribution guidelines 24

LANGUAGES Language Package + + + R pkgdown Python Sphinx C++ Doxygen doxyYoda Julia Documenter.jl Notebooks / MyST Sphinx myst jupytext 26

R

27

JULIA 28

PYTHON 29

GENERIC sphinx is reasonably good for code documentation Static sites can be leveraged for user-documentation

30

C++ 31

PROJECT FILES /** * @file add.h * @author SymEngine Developers * @date 2021-02-25 * @brief Classes and functions relating to the binary operation of ad * * Created on: 2012-07-11 * * This file contains the basic binary operations defined for symbolic * In particular the @ref Add class for representing addition is * @b declared here, along with the `add` and `substract` functions. */ #ifndef SYMENGINE_ADD_H #define SYMENGINE_ADD_H 32

HEADER FILES /** * @brief Create an appropriate instance from dictionary quickly. * @pre The dictionary must be in canonical form. * @see `Mul` for how `Pow` gets returned. * @see `Basic` for the guarantees and expectations. * @param coef the numeric coefficient. * @param d the dictionary of the expression without the coefficien * @return `coef` if the dictionary is empty (size 0). * @return `Mul` if the dictionary has one element which is a `Mul` * @return `Integer` if the dictionary has one element which is a * `Integer`. * @return `Symbol` if the dictionary has one element which is a `S * @return `Pow` if the dictionary has one element which is a `Pow` * @return `Add` if the size of the dictionary is greater than 1. */ static RCP from_dict(const RCP &coef, umap_basic_num &&d); 33

SOURCE FILES /** * @details This function ensures that each term in *dict* is in canoni * form. The implementation in the form of a exclusion list (defaults * true). * * @note **Canonical form** requires the existance of both `coef` and * `dict`, so `null` coefficients and purely numerical (empty dictiona * are also not considered to be in canonical form. Also, the ordering * important, it must be `(coeff, dict)` and **not** `(dict, coeff)`. * * Some **non-cannonical** forms are: * - @f$0 + x@f$. * - @f$0 + 2x@f$. * - @f$ 2 \times 3 @f$. * - @f$ x \times 0 @f$. * - @f$ 1 \times x @f$ has the wrong order. * - @f$ 3x \times 2 @f$ is actually just @f$6x@f$. */ bool Add::is_canonical(const RCP &coef, const umap_basic_num &dict) const 34

BASE DOXYGEN Is ugly Not mobile friendly 35

EXHALE Cannot include source code 36

DOXYREST Includes more structure than exhale Can be extended to other source languages Has a rather complicated setup 37

DOXYYODA 38

TRANSLATIONS At the user level, e.g. with docusaurus cat irhpc.github.io/i18n/is/docusaurus-plugin-content-docs/current/intro

40

REVIEWING DOCUMENTATION 42

DOCUMENTED FALLACIES """ This function adds two numbers """ def sum(a,b): return a*b 43

INVALIDATE OFTEN Documentation cannot typically be tested julia aside

44

CONCLUSIONS 46

OMITTED TOPICS Web development and design Including frameworks and UX Continuous integration How to ensure documentation is coupled to working code Benchmarking Demonstrating code superiority Code Review Practices Scrum and teamwork Multi-language API Where code from different languages are called together 47

FURTHER RESOURCES Describes the present SOTA for documentation practices in the context of a large multi-language project A large scientific code project designed with a user- wiki, SymEngine and the Season of Docs d-SEAMS [goswamiDSEAMSDeferredStructural2020] 48

KEY TAKEAWAYS Document at every level Use the best tools for the job Internationalize only where necessary User level Ensure documentation expires Keep provenance Ensure a documentation style guide is present Lint automatically 49

THE END 51

BIBLIOGRAPHY Goswami, Goswami & Singh, D-SEAMS: Deferred Structural Elucidation Analysis for Molecular Simulations, Journal of Chemical Information and Modeling, 60(4), 2169-2177 . . [goswamiDSEAMSDeferredStructural2020] doi 52

THANKS! 53