Ford documentation: improvements

[jvdp1]

Related to #783 by @ZedThree

Proposition:

• Ford: upgrade from 6.1.10 to 7.0.5
• exclude all BLAS/LAPACK source files from the ford processing (2 reasons: 1) too many procedures; 2) no support of both fypp and cpp by ford)
• stdlib_str2num.fypp: small fixes for ford processing

[jvdp1]

@ZedThree it seems that this latest version of ford (7.0.5) does not generate the links between the specs to the code, e.g., for call [[stdlib_sorting(module):ord_sort(interface)]]( array[, work, reverse ] ). Has the notation been changed between 6.1.10 and 7.0.5?

Also, it seems that it is not possible to exclude files in 6.1.10. Hence, the need to upgrade ford to 7.0.5.

[gareth-nx]

Thanks for this.

IMO it would be good to include documentation for the BLAS/LAPACK interfaces, if not the individual routines for each precision. Otherwise I think it will be very easy for users to become confused about what is available.

I'm not sure whether your pull request keeps the interfaces or not?

[jvdp1]

IMO it would be good to include documentation for the BLAS/LAPACK interfaces, if not the individual routines for each precision. Otherwise I think it will be very easy for users to become confused about what is available.

I'm not sure whether your pull request keeps the interfaces or not?

A description of BLAS/LAPACK is available in the specs. It was decided that only a link would be provided to the individual LAPACK interfaces.

However, I will try to find a way to process only one of the precisions. It could be indeed useful.

[gareth-nx]

A description of BLAS/LAPACK is available in the specs. It was decided that only a link would be provided to the individual LAPACK interfaces.

Yes, to me it would be good to also have the available procedures in BLAS/LAPACK listed somewhere

However, I will try to find a way to process only one of the precisions. It could be indeed useful.

Totally agree, thanks.

[perazz]

These changes look great to me.
@jvdp1 @gareth-nx @ZedThree: In PR #786 I've addressed the FORD syntax issues, so, FORD can now process all BLAS and LAPACK sources just fine. However, I do confirm that it is a lengthy process (at least on my Mac).

I think that the best thing to do would be to exclude the sources, and have FORD only parse the interface blocks. However, FORD will fail in this case (because it cannot find the module procedures in the interface), so, this selective exclusion does not look viable.

[ZedThree]

@ZedThree it seems that this latest version of ford (7.0.5) does not generate the links between the specs to the code, e.g., for call [[stdlib_sorting(module):ord_sort(interface)]]( array[, work, reverse ] ). Has the notation been changed between 6.1.10 and 7.0.5?

This should still work, I'll investigate

[ZedThree]

@jvdp1 The issue with that particular example in stdlib_sorting.md is that it is within backticks:

##### Syntax

`call [[stdlib_sorting(module):ord_sort(interface)]]( array[, work, reverse ] )`

and in Ford v7 the priority has changed such that backticks now (correctly IMO) are always formatted verbatim, so this needs to be something like:

##### Syntax

`call` [[stdlib_sorting(module):ord_sort(interface)]] `( array[, work, reverse ] )`

A quick search shows about 270 examples of links within code blocks like this. A minimal change to ford to restore the old behaviour is:

modified   ford/_markdown.py
@@ -271,7 +271,7 @@ class FordLinkExtension(Extension):
     def extendMarkdown(self, md: MetaMarkdown):  # type: ignore[override]
         project = self.getConfig("project")
         md.inlinePatterns.register(
-            FordLinkProcessor(md, project=project), "ford_links", 174
+            FordLinkProcessor(md, project=project), "ford_links", 194
         )
 

but this would really need to be user-configurable, as otherwise it's not possible to write links verbatim (in general, nesting of inline markup is a bit of a nightmare of conflicting syntax, so this will always be a compromise).

If there's a strong desire for this, I can add this option and get it out in 7.0.6

[jvdp1]

Thank you @ZedThree for your explanations.

If the following syntax works with Ford v7, I can modify the specs within this PR to support it

##### Syntax

`call` [[stdlib_sorting(module):ord_sort(interface)]] `( array[, work, reverse ] )`

If there's a strong desire for this, I can add this option and get it out in 7.0.6

No need to revert it IMO. We can adapt these notations.

[jvdp1]

@perazz @ZedThree @gareth-nx :

Currently, this PR does:

• Ford: upgrade from 6.1.10 to 7.0.5
• Fix all the specs to comply new Ford rules
• Exclude all LAPACK source files from the Ford processing (reason: 1) too many procedures => too long)

Processing the BLAS files does not significantly influence the time of the CI.

I propose that we merge this PR as is, even if the LAPACK files are excluded for ford. The main reason is to reduce the time of the CI of other PR.

[perazz]

LGTM @jvdp1

[perazz]

If there was a way to include the LAPACK interfaces (stdlib_linalg_lapack.f90), without FORD looking for all module procedure implementations (stdlib_linalg_lapack_*.f90), it would be great, but to the best of my knowledge, it is not possible.

[gareth-nx]

Thanks @jvdp1, this looks good. I agree it makes sense to exclude Lapack until we can address the doc build times.

[jvdp1]

Thank you for your reviews.

If there was a way to include the LAPACK interfaces (stdlib_linalg_lapack.f90), without FORD looking for all module procedure implementations (stdlib_linalg_lapack_*.f90), it would be great, but to the best of my knowledge, it is not possible.

I tried several things similar to your proposition, but all failed! @ZedThree do you have maybe an idea? If not, I will wait a few more days and then merge it.

[ZedThree]

There is the (slightly unintuitive) display: none option that stops the rendering of any children of an entity -- except that it seems we still actually process the docstring, we just don't display it, which doesn't help.

It should be possible to fix this, unfortunately I'm at a conference basically all this week, so it might take me awhile to look into it. A quick hack does show some improvement:

modified   ford/sourceform.py
@@ -612,6 +612,10 @@ class FortranBase:
     def filter_display(self, collection: Sequence) -> List:
         """Remove items from collection if they shouldn't be displayed"""
 
+        for obj in collection:
+            if not self._should_display(obj):
+                self.source_file._to_be_markdowned.remove(obj)
+
         return [obj for obj in collection if self._should_display(obj)]

but there still seems to be a pretty big slowdown.

[jvdp1]

Thank you @ZedThree for your comment. There is no rush for this issue IMO. I will merge this PR as is.
You can look at this issue later if you want, and when you have time.