First steps towards a useful developer documentation

[yoricklassmann]

At long last I have found some time to look into #11. It turns out that FORD works out of the box, but produces rather shabby looking documentation and there are a couple of warnings still, that relate to FORD complaining about some DOXYGEN stuff:

Warning: Error parsing src/modules/BundleModule.f90.
        Preceding documentation lines can not be inline:       class(T_TrajectoryBundle), intent(inout) :: B1 !> Bundle

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 53.90%. Comparing base (86dd529) to head (e8e6fdd).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #42      +/-   ##
==========================================
- Coverage   54.08%   53.90%   -0.19%     
==========================================
  Files          41       41              
  Lines        5985     6007      +22     
  Branches      807      810       +3     
==========================================
+ Hits         3237     3238       +1     
- Misses       2399     2419      +20     
- Partials      349      350       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[yoricklassmann]

Building the docs is straightforward:

1. Install FORD with your favorite package manager
2. Execute ford openfms_docs.md

That's it.

[danielhollas]

Thanks for looking into this Yorick!

I'll have a closer look later, but in the meantime, can you please add a new CI job to run Ford build to make sure that the doc building works. You can add a new job to the lint.yml file:

https://github.com/ispg-group/openfms/blob/main/.github%2Fworkflows%2Flint.yml

Also, I noticed that FORD has an option to parse doxygen-style comments. Can you try to enable it and see how it looks like. If we could avoid reformatting all the existing documentation that would be great.

[danielhollas]

Looks like the private statement got deleted here.

[yoricklassmann]

Do we really need it? I would prefer to specify in code that it is private, or leave it out because in the documentation it will show the visibility anyway. I'd prefer the former.

[yoricklassmann]

However, this should not be part of the current PR, so I've reverted to the original.

[yoricklassmann]

Thanks for looking into this Yorick!

I'll have a closer look later, but in the meantime, can you please add a new CI job to run Ford build to make sure that the doc building works. You can add a new job to the lint.yml file:

https://github.com/ispg-group/openfms/blob/main/.github%2Fworkflows%2Flint.yml

Ok will do

Also, I noticed that FORD has an option to parse doxygen-style comments. Can you try to enable it and see how it looks like. If we could avoid reformatting all the existing documentation that would be great.

Yes, that's the case, and generally works quite well, but for some reason the documentation in the example didn't get produced even though FORD can indeed parse doxygen-style comments...

I think what it doesn't like is when you have something like in the TrajectoryModule where variables are just written on one long line, with & line breaks added in the aid of readability. Compare that for example with ElecStrucModule where the variables are separately defined, then FORD produces nice docs.

[danielhollas]

Currently on a Cross country train without good internet so wasn't able to test yet, but have two asks for CI. Can you also please add a short section about how to build and read the docs in the CONTRIBUTING.md guide. Later we can add more about the style guide questions that you raised in the linked GH issue.

[danielhollas]

I've now had a brief time to test this, looks nice!

Sorry for a piecemeal review, there are some more things to tweak.

Also please add short paragraph to CONTRIBUTING.md as noted above.

[danielhollas]

So docs directory actually contains the documentation Overleaf. Apparently, FORD uses doc by default, which is confusing. Can you please add the output_dir option to the configuration. I would use developer_docs/, but am open to other suggestions. We should then use this consistently to distinguish it from documentation for users, so e.g. I would rename this CI job to dev-docs-build or something like that

[danielhollas]

Whatever output directory we decide, we should also add it to .gitignore. Thanks!

[danielhollas]

This is prek specific

Suggested change

	env:
	SKIP: 'no-commit-to-branch'

[danielhollas]

Let's put something here, e.g.

Suggested change

	Test
	Auto-generated developer documentation for OpenFMS

[danielhollas]

It's perhaps debatable if we want to include the private stuff. I feel like if I was browsing this autogenerated documentation (instead of reading the source code directly) I would appreciate the more high-level public-only view. But I don't know, I am also fine with including private stuff this in this PR.

[danielhollas]

Let's rename the this file to a more specific name. Maybe ford_config.md?