Documentation generation on my local machine and on github gives different outcomes about ford HOT 6 CLOSED

Hi Jules, my initial guess is that this is something to do with checking out the code -- Ford can't find some files that are maybe in an external library or git submodule perhaps?

If you try a clean checkout locally, do you see the same issue?

from ford.

@ZedThree Here is the odd thing. If you look at the GitHub Actions output you'll see (for example):

Preprocessing /home/runner/work/MAPL/MAPL/generic3g/couplers/esmf-way/CouplerMetaComponent.F90
Warning: error when preprocessing 
/home/runner/work/MAPL/MAPL/generic3g/couplers/esmf-way/CouplerMetaComponent.F90
:
cpp -traditional-cpp -E -DUSE_MPI=1 -DBUILD_WITH_PFLOGGER=1 
-DBUILD_WITH_EXTDATA2G=1 -DUSE_FLAP=1 -DH5_HAVE_PARALLEL=1 -DTWO_SIDED_COMM=1 
-DMAPL_MODE=1 -I/home/runner/work/MAPL/MAPL/include 
-I/home/runner/work/MAPL/MAPL/gFTL/install/GFTL-1.13/include/v1 
-I/home/runner/work/MAPL/MAPL/gFTL/install/GFTL-1.13/include/v2 
/home/runner/work/MAPL/MAPL/generic3g/couplers/esmf-way/CouplerMetaComponent.F90
/home/runner/work/MAPL/MAPL/generic3g/couplers/esmf-way/CouplerMetaComponent.F90
:2:2: fatal error: Generic.h: No such file or directory
    2 | 
      |  ^          
compilation terminated.

Reverting to unpreprocessed file

However, we have this file excluded, we think:

exclude: **/EsmfRegridder.F90
...
         **/generic3g/couplers/esmf-way/CouplerMetaComponent.F90

Note that we also tried:

         ../../generic3g/couplers/esmf-way/CouplerMetaComponent.F90

and it still didn't exclude it.

Is there perhaps something we are doing wrong to exclude that file? Maybe if we get the syntax right, we can figure out all the other issues...

from ford.

This is actually a bug, the paths in the settings file are supposed to be relative to the setting file, but (at least) the exclude paths get processed relative to where you run ford, and for some reason **/filename doesn't match filename.

For now, a workaround is to just run ford in the same directory as the settings file, that is, run cd docs/Ford; ford mapl3docs-with-remote-esmf.public_private_protected.md. This seems to work for me

Some notes for myself:

This is here:

When ford is run at the top level, then:

fnmatch(os.path.relpath(src), exclude)

becomes:

fnmatch('generic3g/couplers/esmf-way/GenericCoupler.F90', '**/generic3g/couplers/esmf-way/GenericCoupler.F90')

which is False -- which feels a little surprising to me! It might be better to switch to glob.glob(exclude, recursive=True) for pruning the file list, but also os.path.relpath needs to have the second argument with the path of the settings file here

from ford.

This is actually a bug, the paths in the settings file are supposed to be relative to the setting file, but (at least) the exclude paths get processed relative to where you run ford, and for some reason **/filename doesn't match filename.

For now, a workaround is to just run ford in the same directory as the settings file, that is, run cd docs/Ford; ford mapl3docs-with-remote-esmf.public_private_protected.md. This seems to work for me

Ah ha! And I bet both @JulesKouatchou and myself always run ford from the docs/Ford directory because of course we would. But my Github Action didn't do this because, well, I got something working and went hands off.

I'll test this soon.

--

A query @ZedThree: assuming this all works, what is the "right" way to exclude a specific filename in one subdir but not another? Is it:

**/dir1/dir2/file

or:

../../dir1/dir2/file

(since we know exactly where things are relative to the ford control file)

Note we probably have to be specific like this with subdirs, because MAPL3 is slowly becoming based more on path so we might have:

generic3g/foo/bar/module.F90
generic3g/hah/lol/module.F90

and maybe hah/lol is currently a stub that ford can't process (because it's not valid Fortran), but foo/bar is real code that it can. (We do not build hah/lol/module.F90 because it's not in our CMakeLists.txt but ford, of course, is not processing the CMake, it's just looking for Fortran!)

from ford.

A query @ZedThree: assuming this all works, what is the "right" way to exclude a specific filename in one subdir but not another? Is it:

The benefit of the ** notation is that you can exclude similar directories no matter where they appear in your project structure.

The second one is perhaps a bit more explicit, with the downside of maybe being more fragile if you ever rearrange your project directories.

from ford.

@ZedThree Makes sense. We'll stick with the **.

And good news! With your workaround--and some more excludes--we have some docs: https://geos-esm.github.io/MAPL/mapl3-doc/

🎉

Now it's time to start enforcing style, etc. as bits are leaking into places. 😄

MAPL

MAPL is a foundation layer of the GEOS architecture, whose original purpose is to supplement the Earth System Modeling Framework (ESMF)

from ford.