Documentation

[milancurcic]

Use this issue how to best document the stdlib. I put a placeholder Markdown file here.

[jvdp1]

Regarding the documention, is it planned to use some tools, like Doxygen or Ford to generate documention from the code?

[certik]

I think we should write documentation as comments in the code and generate nice html documentation from it, that way the documentation and code is at one place and easier to maintain and keep in sync. So whatever tool allows us to do that, or if we have to write or improve some tools, I think we should do that.

[zbeekman]

FORD is my preference unless someone knows a good way to do that with sphinx.

I think it can be worthwhile to have additional docs. I like hosting markdown based docs on RTD and API docs on gh-pages.

[certik]

Down the road I would like to use LFortran to execute "doctests" just like in Python. Here is the issue for it: https://gitlab.com/lfortran/lfortran/issues/73

[ivan-pi]

FORD also supports the option to include additional markdown based docs (http://d3denergetic.github.io/FIDASIM/ is my favourite example).

Personally, I find the FORD generated documentation easier to navigate than doxygen. In case we decide to use FORD we should agree on the symbols to indicate documentation and whether we use preceding documentation strings or not.

I am not sure if FORD can be used together with jin2for. Does one only document the generic interface block in that case?

cc: @cmacmackin

[cmacmackin]

@ivan-pi I've never used jin2for so I can't be certain. However, FORD does allow files to be preprocessed prior to it parsing for documentation, so that could work. You'd probably want to give a detailed explanation only in the generic blocks, but still document the arguments in each specific implementation.

[marshallward]

MOM6 uses Doxygen-style comments, but these are converted into reST files which are then passed onto Sphinx.

An example Doxygen-marked file: https://github.com/NOAA-GFDL/MOM6/blob/dev/gfdl/src/parameterizations/vertical/MOM_vert_friction.F90

This uses the !<and !! syntax for marking up variables, subroutines, etc.

The Doxygen XML is then converted to reST by a local tool developed by a former visitor (itself forked from another project): https://github.com/angus-g/sphinxcontrib-autodoc_doxygen

although we are looking to migrate to this tool: https://github.com/vovkos/doxyrest

Once it's been converted to reST, then we just run it through the usual Sphinx process.

This is the generated output: https://mom6.readthedocs.io/en/dev-gfdl/api/generated/modules/mom_vert_friction.html#f/mom_vert_friction

Some limitations of the above system are that the Doxygen -> reST process depends on an unsupported tool which only exposes a fraction of the Doxygen content, and that there are apparently bugs inside of Doxygen's Fortran support which prevent adoption of doxyrest (which is a supported tool). We have someone here working on this problem, but it's not ready to go at this moment.

Not necessarily advocating this approach BTW, only hoping to show what alternatives are out there and what is possible.

I agree with others that the native Doxygen output is not that pleasant to navigate, and I don't think we'd continue to use it if we didn't have the pipeline above.

[zbeekman]

I am not sure if FORD can be used together with jin2for. Does one only document the generic interface block in that case?

I usually generate the sources with jin2for then run FORD on those.

[zbeekman]

I do quite like Sphinx but the Doxygen to Sphinx pipeline seems complicated. Ideally whichever tool we choose will be Fortran aware enough to provide additional useful information beyond the source file markup.

For high-level documentation I really like read-the-docs and using mkdocs. E.g., https://zstdfortranlib.readthedocs.io/en/latest/?badge=latest (WIP)

[jvdp1]

I think it would be a good time to introduce a documentation.
Several modules are now present in stdlib, and it would be useful to have some documentations to show what is already implemented to the new contributors (and users).

From the different comments, it seems that FORD could be a good tool for generating a doc from Fortran files, while @marshallward and @zbeekman proposed more complicated (better?) approaches. Should we give a try to FORD first?

[certik]

Does FORD support Markdown? I would suggest to write our documentation in Markdown in the comments. We can start with FORD.

…

On Sun, Jan 5, 2020, at 7:11 AM, Jeremie Vandenplas wrote: I think it would be a good time to introduce a documentation. Several modules are now present in `stdlib`, and it would be useful to have some documentations to show what is already implemented to the new contributors (and users). From the different comments, it seems that `FORD` could be a good tool for generating a doc from Fortran files, while @marshallward <https://github.com/marshallward> and @zbeekman <https://github.com/zbeekman> proposed more complicated (better?) approaches. Should we give a try to FORD first? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#4?email_source=notifications&email_token=AAAFAWHO6Q6NIKB2GYF4HRDQ4HTCJA5CNFSM4J25GCIKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIDX2EA#issuecomment-570916112>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAFAWC364JQWTTJ3GEGGDDQ4HTCJANCNFSM4J25GCIA>.

[cmacmackin]

Yes, ford is markdown based.

…

On Sun, 5 Jan 2020, 17:22 Ondřej Čertík, ***@***.***> wrote: Does FORD support Markdown? I would suggest to write our documentation in Markdown in the comments. We can start with FORD. On Sun, Jan 5, 2020, at 7:11 AM, Jeremie Vandenplas wrote: > I think it would be a good time to introduce a documentation. > Several modules are now present in `stdlib`, and it would be useful to > have some documentations to show what is already implemented to the new > contributors (and users). > > From the different comments, it seems that `FORD` could be a good tool > for generating a doc from Fortran files, while @marshallward > <https://github.com/marshallward> and @zbeekman > <https://github.com/zbeekman> proposed more complicated (better?) > approaches. Should we give a try to FORD first? > > — > You are receiving this because you commented. > Reply to this email directly, view it on GitHub > < #4?email_source=notifications&email_token=AAAFAWHO6Q6NIKB2GYF4HRDQ4HTCJA5CNFSM4J25GCIKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIDX2EA#issuecomment-570916112>, or unsubscribe < https://github.com/notifications/unsubscribe-auth/AAAFAWC364JQWTTJ3GEGGDDQ4HTCJANCNFSM4J25GCIA >. > — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#4?email_source=notifications&email_token=AB6ESPIXRLGF4TSO32Z542TQ4IJOJA5CNFSM4J25GCIKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEID3MKQ#issuecomment-570930730>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AB6ESPMT7OMOU33PISZVEA3Q4IJOJANCNFSM4J25GCIA> .

[certik]

Perfect. I would give it a try.

…

On Sun, Jan 5, 2020, at 10:35 AM, Chris MacMackin wrote: Yes, ford is markdown based. On Sun, 5 Jan 2020, 17:22 Ondřej Čertík, ***@***.***> wrote: > Does FORD support Markdown? I would suggest to write our documentation in > Markdown in the comments. We can start with FORD. > > On Sun, Jan 5, 2020, at 7:11 AM, Jeremie Vandenplas wrote: > > I think it would be a good time to introduce a documentation. > > Several modules are now present in `stdlib`, and it would be useful to > > have some documentations to show what is already implemented to the new > > contributors (and users). > > > > From the different comments, it seems that `FORD` could be a good tool > > for generating a doc from Fortran files, while @marshallward > > <https://github.com/marshallward> and @zbeekman > > <https://github.com/zbeekman> proposed more complicated (better?) > > approaches. Should we give a try to FORD first? > > > > — > > You are receiving this because you commented. > > Reply to this email directly, view it on GitHub > > < > #4?email_source=notifications&email_token=AAAFAWHO6Q6NIKB2GYF4HRDQ4HTCJA5CNFSM4J25GCIKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIDX2EA#issuecomment-570916112>, > or unsubscribe < > https://github.com/notifications/unsubscribe-auth/AAAFAWC364JQWTTJ3GEGGDDQ4HTCJANCNFSM4J25GCIA > >. > > > > — > You are receiving this because you were mentioned. > Reply to this email directly, view it on GitHub > <#4?email_source=notifications&email_token=AB6ESPIXRLGF4TSO32Z542TQ4IJOJA5CNFSM4J25GCIKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEID3MKQ#issuecomment-570930730>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AB6ESPMT7OMOU33PISZVEA3Q4IJOJANCNFSM4J25GCIA> > . > — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#4?email_source=notifications&email_token=AAAFAWC5O6NOOW5BCLBZUFLQ4IK43A5CNFSM4J25GCIKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEID3T4I#issuecomment-570931697>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAFAWDBOD4EJHKATAA3TB3Q4IK43ANCNFSM4J25GCIA>.