Documentation update - [merged] #2441

Closed jonmaddock closed 1 year ago

In GitLab by @timothy-nunn on Oct 28, 2021, 16:28

_Merges forked_documentationi -> develop

Supersedes !534

Closes #1403

Closes #1398

Add f2py specific documentation

Fix missing/outdated documentation

Document python-fortran interface

^ all above done within MkDocs to allow as many of our pages as possible to be generated one way

In GitLab by @timothy-nunn on Oct 28, 2021, 16:32

@jonmaddock Find an example of the new docs here: http://tnunn.gitpages.ccfe.ac.uk/process/

In GitLab by @timothy-nunn on Oct 28, 2021, 16:35

added 2 commits

0f3acd06 - Remove legacy pip install of pdoc3
3a8902fe - Keep all untracked files from build (some are required for docs)

Compare with previous version

In GitLab by @timothy-nunn on Nov 16, 2021, 12:17

marked as a Work In Progress

In GitLab by @timothy-nunn on Nov 16, 2021, 12:17

unassigned @jonmaddock

In GitLab by @timothy-nunn on Nov 18, 2021, 13:26

gdb, f2py turning things optional

In GitLab by @timothy-nunn on Nov 24, 2021, 10:43

added 264 commits

3a8902fe...bee5e13b - 261 commits from branch process:develop
964dd97b - Merge branch 'develop' of git.ccfe.ac.uk:process/process into forked_documentation_i
b8e7a705 - F2py style guide for wrapping fortran code in python, added to documentation
1d2df247 - Added docstrings to documentation scripts

Compare with previous version

In GitLab by @timothy-nunn on Dec 8, 2021, 11:27

added 73 commits

1d2df247...632b930d - 71 commits from branch process:develop
bcf73aa3 - Merge branch 'develop' of git.ccfe.ac.uk:process/process into forked_documentation_i
0e678bb5 - Disable vardes page, add debugging page

Compare with previous version

In GitLab by @timothy-nunn on Dec 8, 2021, 15:09

unmarked as a Work In Progress

In GitLab by @timothy-nunn on Dec 8, 2021, 15:15

NOTE: the tracking page will not work on this fork because it does not have the correct CI key

In GitLab by @timothy-nunn on Dec 20, 2021, 14:18

added 1 commit

59b1aa8d - Updated debugging docs

Compare with previous version

In GitLab by @timothy-nunn on Dec 21, 2021, 11:10

added 1 commit

8f92134a - mkdocs cannot bolden just y, replaced with brackets

Compare with previous version

In GitLab by @timothy-nunn on Dec 21, 2021, 11:12

added 1 commit

00a14aa3 - Added link to more GDB commands in docs

Compare with previous version

In GitLab by @timothy-nunn on Jan 11, 2022, 10:03

added 1 commit

82129af9 - Move prepeare release outside of testing section

Compare with previous version

In GitLab by @timothy-nunn on Jan 11, 2022, 10:33

added 1 commit

d85f7079 - Move prepeare release outside of testing section

Compare with previous version

klassic!

Will this make a newline in the body for each __ dunder function (for each "" in list at :66)? No big deal if it does, but could look weird if there are lots of dunder funcs.

What char is ord(c) == 0 and why are we asserting its absence? Could I get a comment please?

So the presence of non-empty doc attribute is the qualifier for a function rather than a variable, right? Could you comment that?

Is it perhaps worth putting a docstring at the top of the produced file so it's obvious it's a dummy Python module only for auto-documentation purposes? It's not totally clear what the difference between process.fortran and process._fortran are otherwise. Perhaps a file rename? Just something to make it obvious would be great.

As you know, I usually get antsy when I don't see docstrings, but this is so well-written and clear (and a script), so I'm happy without.

document_fortran_interface.py is an excellent solution for getting all our Python and Fortran docs into the same Python auto-documentation tool. Brilliant!

Hey, mkdocstrings is neat!

Should test-setup-py38 (or test-setup, even) depend on make-py38 instead? Isn't this an indirect dependency as it stands?

These could probably go into requirement.txt, as I understand it. But I'm happy to be corrected! Perhaps this could be included in your larger CI cleanup task instead.

Do we need to cd here?

Ok, re-install once _fortran.py is in the process package so it can be read by mkdocstrings? Nice! Can you doc why the re-install is required here

Don't quite understand this I'm afraid. Which files are required for the docs? Should they be included in the package when it's built? Maybe I'm missing something obvious!

Surely should quack?

Really? Nice spot

These f2py docs are excellently written, great examples!

In GitLab by @timothy-nunn on Jan 17, 2022, 09:08

Commented on scripts/document_fortran_interface.py line 76

create_function_signature creates a Python signature for a wrapped subroutine. The auto documenter then documents this Python file. This will cause each dunder method to cause a new line in the script which does not matter since that script is just an intermediate form. No dunder methods on these wrapped modules are documented.

In GitLab by @timothy-nunn on Jan 17, 2022, 09:09

Commented on scripts/document_fortran_interface.py line 80

I will comment this in the code - I was having an issue with corrupted/weird characters in the docstring of some of the wrapped subroutines, I believe I can safely remove this.

In GitLab by @timothy-nunn on Jan 17, 2022, 09:10

Commented on scripts/document_fortran_interface.py line 100

Absolutely, I will make it clear that _fortran contains abstract definitions.

In GitLab by @timothy-nunn on Jan 17, 2022, 09:11

Commented on .gitlab-ci.yml line 367

Yes it is but as you will see in some of my upcoming requests, I will add this in a lot to increase the parallel running of the slow bits of the CI (like the tracker).

In GitLab by @timothy-nunn on Jan 17, 2022, 09:11

Commented on .gitlab-ci.yml line 295

Very true, I am also not sure if this is needed anymore - I must check

In GitLab by @timothy-nunn on Jan 17, 2022, 09:14

Commented on documentation/proc-pages/development/f2py-standards.md line 26

I will slip this in with another commit - I dont know if I want "make duck quack" as a commit in the history -- or maybe I do actually :D

In GitLab by @timothy-nunn on Jan 17, 2022, 09:17

Commented on .gitlab-ci.yml line 145

Again, this may be a relic from remote building on PROCESS-STEP - I will check. Or, it could be to do with the fact we perform a reinstall.

This is the same docstring as FortranModuleMember above; I'm guessing this is for variables only!

List[FortranModuleMember], right?

Is it List[FortranModule]?

Does this have a defined type, e.g. the same as type(fortran.main_module)?

Excellent use of NamedTuples here, really clear.

This is correct, but can you make it clear this is for documentation purposes only?

Nice, Fortran subroutines/functions analogous to class methods.

Why [0]?

When using gdb, I use:

run process/main.py -i tracking/baseline_2019/baseline_2019_IN.DAT

without trouble, not requiring the process_wrapper.py script. I'm fine with this as it is, but am I missing something or is this equivalent?

This is great!

You read my mind!

You amended this in the next commit, so ignore me!

Is it worth renaming this process.fortran to be consistent with the naming convention in this folder?

ukaea / PROCESS

Documentation update - [merged] #2441