fortran-foss-programmers / ford Goto Github PK

I am testing FORD on some of my small and large Fortran projects.

I can get it to work on a few test cases.
But in most cases I am getting errors like below.

Can this be fixed or at least a workaround advised?

Correlating information from different parts of your project...

Traceback (most recent call last):
  File "/usr/local/bin/ford", line 9, in <module>
    load_entry_point('FORD==1.1.0', 'console_scripts', 'ford')()
  File "/usr/local/lib/python2.7/dist-packages/ford/__init__.py", line 152, in main
    project.correlate()
  File "/usr/local/lib/python2.7/dist-packages/ford/fortran_project.py", line 123, in correlate
    if proc.parobj == 'sourcefile': ranklist.append(proc[1])
TypeError: 'FortranSubroutine' object does not support indexing

I find that people interpret release version strings differently, and really like the philosophy behind semantic versioning.

Do you have a well defined policy for versioning releases?

Would it make sense to adopt semantic versioning?

I know people often have trepidation about bumping a release of new software from 0.x—which they may think connotes some sort of new-ness or immaturity of the package—to 1.x, fearing some sort of over promise in terms of stability, function and lack of bugs. I find, however, that software will always have bugs, and clarity about API consistency, functionality and backwards compatibility far out weigh any concerns of over promising.

Great job with FORD! I'm starting to use it in earnest, and will pass along some suggestions as they occur to me. I was wondering if, on the procedure page (for example this one), we could have the options to:

• not include the local variable declarations. In this case, I just want to show the subroutine arguments, but the user doesn't need to know about the local variables.
• display the syntax-highlighted source code for the routine here on this page. Maybe at the bottom of the page? I think that would be very convenient.

I was wondering if it was necessary to display the metadata in the module procedures listings for an interface. See example below. I would say leave it out, since in this case, I think it is the description that is most useful. I think it would look cleaner without the metadata (my opinion...free free to ignore).

Maybe include an alternate way to specify a documentation block (predocmark or docmark) by defining a docmark that indicates that the documentation is starting, and will continue until the comment block ends. That way you don't have to include the docmark on every line, just the first one. Example (say, let predocmark_alt=#):

!#
!  This is an example. 
!  Here is another line of comments.
!  
!  History
! ----------
!  * 1/1/2000 Created

subroutine blah()

end subroutine blah

What do you think? I think it makes the source look cleaner.

Hi Chirs,

During the porting of all my other Fortran codes from doxygen to Ford I have realized that it would be a very nice feature to have the possibility to activate a "verbose checking" that will advice for entities that Ford has recognized without a documentation. As an example, ford -warnall ... prompting to stdout something like paranoiac advice for undocumented entities.

file bar.f90

function ciccio(pinco) result(pallo)
implicit none
integer:: pinco ! not documented
logical:: pallo !! well documented
...
endfunction ciccio

Ford paranoiac mode

ford -warnall bar-project-file.md
...
warning: variable 'pinco' is not documented! line 3 of file bar.f90
...

I just upgraded (I think!?) to the latest patch using pip/pypi but it would be awesome if you added a -v or -V or --version flag so that users who install ford through that avenue can easy check which version they have…

Great work 👍

One thing that might be handy would be to have the ability to include non-Fortran source files in the documentation. Some ideas:

• They would not be parsed, but would be included in the list of source files.
• If they were a known source code format (say, C), then they could also be syntax highlighted.
• Include the ability to have a source file level documentation block (one that applies to the file itself, rather than to a specific variable or procedure). It would appear at the top of the source file page, and be parsed as Markdown, etc. like normal. This may also be handy for normal Fortran files (or say, an old school .for file that is just a bunch of subroutines). For non-Fortran files, it would have to account for the different comment characters in the different languages.

What do you think? This is probably a longer-term feature, but I think it would be quite handy. I have several use cases for this (e.g., a shell script that goes with a program, or a C-header file that defines the C-bindings to the Fortran code, etc.).

I've run into a problem when using FORD to document code that uses a library which introduces other variable types, and these are not recognised by FORD.

Specifically I'm using the PETSc library, which is written in C, but provides interfaces so you can use it from Fortran. In your code you put in preprocessor #include statements to get access to the variable types and routines you need (for parallel vectors, matrices, linear and nonlinear solvers, etc.) When you declare variables of these new types, you don't use e.g. type(Vec) :: v, you just declare Vec :: v. Which is why FORD doesn't pick them up. Instead it either ignores them, or sometimes comes up with an "Invalid variable declaration" error.

It looks like FORD has a couple of regexps in sourceform.py that detect variable types: VAR_TYPE_RE, and VARIABLE_RE (the latter in the FortranContainer class). These appear to hard-code the variable types that are recognised.

Do you think it would be possible to add an option in the project file so that users could declare additional variable types they are using? These could then be added to those regexps in sourceform.py.

I realise you are busy just now, Chris, but wondered if you thought this idea has any merit, in which case I could perhaps look at working on it myself.

Hi all,

I have just downloaded the latest version and I am currently using it on Lib_VTK_IO. It seems that the new version has an API change not documented.

In the previous version the path of included md files was relative to the path of the project main file. Now it seems that the path is relative to the path where ford is executed.

See you soon.

Python 3 support would be great.

Hi Chris,

Ford is becoming more and more powerful. I think that the number of your users will increase quickly as well as the Ford features list. I suggest to start to exploiting the capabilities of the github WIKI. A good wiki will greatly help new users, more than a single README that will rapidly become too lengthy.

I was wondering if we could have the option of allowing the user to specify a link in the comments from one procedure to another. For example, here I refer to the db2val procedure. It would be great if this was a link that I could click to immediately take me there. RoboDoc does this automatically (so anywhere I have this string, it will be a link to the procedure)...but sometimes this is too aggressive. It would be nice if I could specify them using something like [db2val] or [bspline_module:db2val] and have this be converted to a link.

My application suite keeps its source in src/ and also /libsrc.
I would like the documentation to go in doc/
However ford only allows one project_dir value and gives the error

Error: output directory a subdirectory of directory containing source-code
~~~`
if I put doc/ as the output_dir

Is there a suggested fix or workaround perhaps by using --exclude?

FORD will crash if it encounters a one-line documentation comment containing a colon. That is because it is interpreting it as metadata and then can't seem to handle the syntax (the fact that there are multiple words before the colon, perhaps). Not 100% certain what causes the crash, but that's besides the point. There needs to be some way for people to make it clear that the first line of their documentation does not contain any metadata.

The author metadata is doing something odd. Example:

!*****************************************************************************************
!> author: blah
!
!  blah blah.
    subroutine blah()

    end subroutine blah
!*****************************************************************************************

For

predocmark_alt: >

The output page looks like this:

(I'm using the latest PyPi version).

In json-fortran we are using some preprocessor macros, which is causing ford to crash. Consider the following dumbed-down example:

blah.F90

module blah_module

private

#define MACRO(PROCEDURE) PROCEDURE , wrap_/**/PROCEDURE

    type,public :: blah
        !! blah
    contains
        generic,public :: info => MACRO(blah_info)  !blah blah blah        
        procedure :: MACRO(blah_info)        
    end type blah

    contains

    subroutine blah_info(me,i)
    !! blah info
    class(blah),intent(in) :: me
    integer,intent(in) :: i
    end subroutine blah_info

    subroutine wrap_blah_info(me,r)
    !! wrap blah info
    class(blah),intent(in) :: me
    real,intent(in) :: r
    end subroutine wrap_blah_info

end module blah_module

blah.md

project: blah
project_dir: ./src
output_dir: ./doc
summary: blah blah

The error message is:

Traceback (most recent call last):
  File "/Users/anaconda/bin/ford", line 9, in <module>
    load_entry_point('FORD==2.1.0', 'console_scripts', 'ford')()
  File "/Users/anaconda/lib/python2.7/site-packages/ford/__init__.py", line 201, in main
    ford.output.print_html(project,proj_data,proj_docs,page_tree,relative)
  File "/Users/anaconda/lib/python2.7/site-packages/ford/output.py", line 199, in print_html
    html = template.render(proj_data,dtype=dtype,project=project)
  File "/Users/anaconda/lib/python2.7/site-packages/jinja2/environment.py", line 969, in render
    return self.environment.handle_exception(exc_info, True)
  File "/Users/anaconda/lib/python2.7/site-packages/jinja2/environment.py", line 742, in handle_exception
    reraise(exc_type, exc_value, tb)
  File "/Users/anaconda/lib/python2.7/site-packages/ford/templates/type_page.html", line 1, in top-level template code
    {% extends "base.html" %}
  File "/Users/anaconda/lib/python2.7/site-packages/ford/templates/base.html", line 93, in top-level template code
    {% block body %}
  File "/Users/anaconda/lib/python2.7/site-packages/ford/templates/type_page.html", line 61, in block "body"
    {{ macros.bound_info(bp) }}
  File "/Users/anaconda/lib/python2.7/site-packages/ford/templates/macros.html", line 307, in template
    <div class="panel-heading codesum"><a class="anchor" name="bp-{{ tb.name }}"></a><h3>{% if tb.generic -%}generic,{% else %}procedure,{%- endif %} {{ tb.permission }}{% if tb.attribs -%}, {% for attrib in tb.attribs -%}{{ attrib }}{% if not loop.last -%}, {% endif %}{%- endfor %}{%- endif %} :: <strong>{{ tb.name }}</strong> {% if tb.generic or tb.name != tb.bindings[0].name %} => {% for bind in tb.bindings -%}{% if bind.permission in bind.parent.display %}{{ bind }}{% else %}{{ bind.name }}{% endif %}{% if not loop.last -%}, {% endif %}{%- endfor %}{% endif %} {% if tb.binding|length == 1 %}<small>{{ tb.bindings[0].proctype }}</small>{% endif %}
  File "/Users/anaconda/lib/python2.7/site-packages/jinja2/environment.py", line 397, in getattr
    return getattr(obj, attribute)
jinja2.exceptions.UndefinedError: 'str object' has no attribute 'parent'

Maybe it's looking for a procedure called MACRO(blah_info) and can't find it? I guess I don't expect it to be able to process the macros, but maybe it could gracefully handle this somehow with a warning message or something? What do you think?

Thanks!

|media| does not seem to be correctly expanded in the documentation of subroutines and functions, but would be very useful for some applications.

Hi Chris,

I have not yet used Ford, thus I may be wrong, but reading your doc it seems that the output is only html. I suppose that inside Ford you first build markdown files, is it right? It would be very useful to have also the possibility to have markdown output besides the html one.

See you soon.

The links need to be made consistent. Trivial fix, but it cannot install like it is.

Quick fix is to link README.rst to README.md

The {{filename}} syntax of my Markdown-Include extension isn't quite as error-proof as I'd hoped. Occasionally, in LaTeX equations or in code fragments, people will use a {{ and a }} somewhere, which causes an incorrect error-message to be printed and that text to be removed. Will probably need to come up with some new syntax.

Hi Chris,

One feature of doxygen I am addicted is the @note statement that triggers a note environment putting the doc-string following the maker into an emphasized box (paragraph).

Can you add such a feature to the todo list?

See you soon.

This snippet gives the following error.
~
$ head -2 danfe.md
project_dir: ./danfe
output_dir: ./danfe_doc
$ ford/ford.py -ef danfe.md
Error: output directory a subdirectory of directory containing source-code.

Note that I found a workaround by adding a '/' to the end of project_dir however I should not have to do this

Hi Chris,

I am trying Ford (http://szaghi.github.io/FLAP/index.html) and... it is great! It will be main doc tool, bye bye doxygen :-)

Unfortunately, you will bored by my messages :-(

I have another feature request: is it possible to have a sort of "include" statement for including other markdown files into the main project one? e.g. the classical README.md...

See you soon.

Some suggestions for the procedure pages. Maybe, for the columns (Type, Intent, etc...) do the following:

• Strip away the trailing commas (so integer rather than integer,). It would look cleaner that way I think.
• For Intent, since the column already says "Intent", maybe just use in, out, etc. (rather than intent(in), etc.) Not a big deal, feel free to ignore this one.

hi, I have come across a weird problem: if I set up a test project with a source directory containing these two files:

bob.F90:

module bob_module

end module bob_module

fred.F90:

module fred_module

  use npk_module

end module fred_module

and run FORD on it with the following config file:

project: Weird problem
project_dir: ./src
output_dir: ./doc/dev
extensions: F90
A very weird problem.

I get the following error:

acro018@des108:~/software/ford/test/super$ ford devdoc.md
Reading file src/fred.F90
Reading file src/bob.F90

Correlating information from different parts of your project...

Traceback (most recent call last):
  File "/usr/local/bin/ford", line 9, in <module>
    load_entry_point('FORD==2.0.0', 'console_scripts', 'ford')()
  File "/home/acro018/software/ford/code/ford/__init__.py", line 171, in main
    project.correlate()
  File "/home/acro018/software/ford/code/ford/fortran_project.py", line 136, in correlate
    ranklist = toposort.toposort_flatten(deplist)
  File "/usr/lib/python2.7/dist-packages/toposort.py", line 81, in toposort_flatten
    result.extend((sorted if sort else list)(d))
  File "/home/acro018/software/ford/code/ford/sourceform.py", line 136, in __lt__
    return (self.name < other.name)
AttributeError: 'str' object has no attribute 'name'

There is no npk_module defined in the source files. (It could be a module defined in a library that I link to- that usually seems to work OK.)

FORD works fine if:

• I add a third file containing a module called npk_module.
• I delete bob.F90.
• I put a 'use fred_module' statement in bob.F90.
• (really weird part) I change the name of npk_module to e.g. npl_module (or various other things, but not mpi_module or some others).

Am I doing something silly or is this a problem?

Hi Chris,
First off, take your time with this one if you like the ideas, there’s no urgency here.

It would be AMAZING to have the ability to change the sorting order in lists and tables generated by FORD. One implementation could be to have sorting specified as meta data or command line switches to pick between say, alphabetical or source order. An even more powerful feature, however, would be some means of letting the user who is browsing the documentation change the sorting. For example, you could sort by visibility, then type, then name for module variables.

I don’t know much about websites and web development, or the tools upon which FORD is built, but dynamic sorting would be really useful when working with a code. If you’re interested and having trouble visualizing what I mean, I could send you an image and a better description…

It is possible to expand exclude to be able to specify directories that are to be excluded?

I've noticed that the header from a predocmark_alt block doesn't show up if there is a blank line between the last comment at the item that is being documented. The normal predocmark doesn't have this issue. Example:

predocmark_alt: >

!> blah blah
!  This one doesn't work

module blah
end module blah

!> blah blah
!  This one works
module blah
end module blah

Dear cmacmackin, your project is very interesting. I am searching for documentation tool tailored to fortran with support to markdown output. However, the readme of ford is "reticent"... are there other docs? examples or tutorials?

My best regards

I just spotted something that looks like a small bug in sourceform.py. In FortranSubroutine._initialize(), line 525 says:

if attribstr.find("elemntal") >= 0:

Looks like a typo in "elemental"- should probably be if attribstr.find("elemental") >= 0: ?

I have found that, when running with large projects, FORD can take several minutes to produce the output. During this time the computer can become sluggish. Simple experiments reveal that this is almost entirely down to the process of producing the search-catalog. I suspect that it is the way in which I am using BeautifulSoup in there which is causing the problem. Nothing else should be that resource-intensive.

Hi Chris,

I have noticed an apparently different behavior of first paragraph trigger with respect the summary: marker.
Consider the following two images:

In the first the summary is triggered by summary: marker, whereas in the second the marker is removed and the summary is triggered by the first paragraph. In both 2 ways the summary is correctly shown (see below), but only without summary: the summary is shown also into the description.

Is this a desired behavior or is it a bug?

Do you have an example of how to use the CodeHilite feature to put source code within the markdown documentation blocks? I can't seem to get it to work. Thanks!

Hi all,
I have done some simple experiments with ford and it looks very
interesting. I have few questions:

1. I have not found any mailing list, is this (github issues) the
   right way to ask questions?

2. I see in the wiki that "FORD documentation must come after whatever
   it is that you are documenting" and "Unfortunately, if you disagree,
   it is unlikely that there will ever be a switch available to change
   this behaviour, as it would require a drastic rewrite of large parts
   of the structure of the code."

Still I wonder whether one could support comments starting with !>
which would refer to the following entity, such as

!> Document variable x
!!
!! Variable x is very useful
integer :: x

I am thinking about a preliminary pass where comments starting with !>
are moved after the entity and then processed; this would not conflict
with the current syntax which uses !! and would allow
a) comments put before the entity, for those who like them
b) a simpler migration from/to doxygen, which already uses !> and !<

If the required work is not too large I could try to contribute, given
my limited python knowledge...

Thanks,
Marco

Ford doesn't work properly on Windows. It is probably due to the directory slash, since it is generating a bunch of files like doc%5Cmodule%5Cblah.html rather than doc/module/blah.html. If this isn't a priority for you, I can probably take a look at it.

hi
I just installed FORD and set up a simple test, but when I run it's crashing with the following error:

No handlers could be found for logger "MARKDOWN"
Traceback (most recent call last):
File "/usr/local/bin/ford", line 9, in
load_entry_point('FORD==1.1.0', 'console_scripts', 'ford')()
File "/usr/local/lib/python2.7/dist-packages/ford/init.py", line 65, in main
extension_configs={'markdown.extensions.codehilite':{'linenums':True}})
File "/usr/lib/python2.7/dist-packages/markdown/init.py", line 134, in init
configs=kwargs.get('extension_configs', {}))
File "/usr/lib/python2.7/dist-packages/markdown/init.py", line 166, in registerExtensions
% (ext.class.module, ext.class.name))
ValueError: Extension "builtin.NoneType" must be of type: "markdown.Extension".

Could this be caused by one of the FORD dependencies being too old? I saw that all of them (apart from markdown-include) were in my package manager (apt on Debian Wheezy), so installed them via apt, then used pip to install markdown-include and finally FORD itself.

Versions of the dependencies are as follows (from pip freeze):
Jinja2==2.6
Pygments==1.5
toposort==1.1
Markdown==2.1.1
beautifulsoup4==4.1.0
markdown-include==0.4.2

Any help appreciated!

Cheers, Adrian

Hi Chris,

The new release is great! The PyPi publishing is very useful.

As future improvment I suggest you to try pybuilder http://pybuilder.github.io

It is very helpful to automate developing/testing/mantainance. In particular, I am very happy with the testing facilities...

Another future improvment could be the refactoring of project tree in order to be more pythonish: put the sources into a main src directory and deploy on PyPi the built releases created, for example, by means of pybuilder. I follow this approach for MaTiSSe (https://github.com/szaghi/MaTiSSe) and this simplifies my life.

I’m just curious if you know what’s going on with some of the badges not rendering correctly when included in FORD documentation. For example take a look here: http://szaghi.github.io/FLAP/index.html in the compiler support section, vs when rendered by github: https://github.com/szaghi/FLAP/blob/master/README.md

Is it the + characters throwing off the markdown renderer? Is this due to FORD or the vendor/upstream markdown rendering FORD uses?

Hi Chris,

Into your doc I read that Ford is triggered by !! mark. It is very useful to have the possibility to customize this marker, e.g. for coders that are using doxygen: tipically the variables docstrings are triggered by !< marker. If the Ford docstrings marker becomes customizabile the modification necessary for "old" projects are strongly reduced.

See you soon

Hi Chris,

I am playing with ford and I like it more and more.

At this page http://szaghi.github.io/FLAP/module/data_type_command_line_interface.html you can find the doc of Type_Command_Line_Interface derived type. As you can see it has a component defined as Type_Command_Line_Argument which is hyper-linked to its own doc page. However, the doc page of Type_Command_Line_Argument is missing.

I guess that is due to the private attribute of the Type_Command_Line_Argument derived type. Is it true?

Is it a bug or a design behavior? In this case, is it possible to create documentation of also private entities?

See you soon.

Hi All,

I am not sure, but I was thinking that the check-list (as in Github flavored markdown) was supported. Some tests with the latest ford installed from PyPi have failed.

For example the md syntax:

* [ ] not check;
* [X] check!

is not well rendered. I am wrong and the check-list was never supported, or has the new version a bug?

See you soon.

Hi Chris,

with the FLAP project I am using for testing ford I find that the doc page of a testing program (FLAP_Test) is not created, see http://szaghi.github.io/FLAP/program/FLAP_Test.html.

Is it a bug or is there a mistake in main ford's project file (https://github.com/szaghi/FLAP/blob/master/doc/main_page.md)?

See you soon.

Hi Chris,

sorry for accidently submitted previous issue - something fell on my keyboard. (it may be deleted of course - if at all possible).
However, today I found the ford tool and I already like it more than other tools with respect to modern fortran. I do some fortran programming as well as fortran teaching at our computation center - and to some extend - tools are also a subject.
I wonder whether it would be relatively easy to have the case of an abtract interface and its usage within an object bound procedure properly implemented (procedure pointer as type component with interface), e.g.:

type my1_t
private
real :: r !! data
integer :: i !! index
procedure(afunc1),pointer,public :: strategy => null()!! object bound
end type my1_t
abstract interface
function afunc1(s)result(x)
import my1_t
class(my1_t), intent(in) :: s
real :: x
end function afunc1
end interface

currently it seams that in the ford-generated documentation does leave the procedure pointer with out interface: procedure() instead of procedure(afunc1)
also the polymorphic type in the argument list of the abstract interface does not show up properly:
class() instead of class(my1_t).

highly appreciate your work anyway.
thanks
Gilbert

The "Source File" link at the top of the page (for example here) is linking to a files/ directory. However, the script actually is putting them in a sourcefile/directory.

Hi Chris,

Very good job! Your new documentation is very useful. It is the first doctool that drives me to leave doxygen to another tool :-)

I read that you are working to extract the inter-modules dependency of files that Ford parses. I have already faced with this problem in FoBiS.py (I see that you using it for your very nice Futility progect, great name!): I am refactoring FoBiS.py for publishing on PyPi, maybe I can create packages of the classes/functions that I wrote for FoBiS.py in order that you can easily integrate them into Ford. Are you interested in? At the end of this week when I come back to office I very curious to try Ford...

See you soon

FORD creates doc/sourcefile/json_module.f90.html but the link in the header/top menu points to doc/sourcefile/json_module.F90.html. The filename is actually json_module.F90

Hi Chris,

I used to define private the type-bound procedures constituting a type-bound generic public interface, e.g. into FLAP there is something like:

type, public:: Type_Command_Line_Interface
  !< Derived type implementing a flexible Command Line Interface (CLI).
  integer(I4P)::                                  Na          = 0_I4P !< Number of CLA.
  ....
  contains
    procedure:: free
    ....
    generic::   get => get_cla_cli,get_cla_list_cli
    ! private procedures
    procedure,              private:: get_cla_cli
    procedure,              private:: get_cla_list_cli
endtype Type_Command_Line_Interface

As you can see here http://szaghi.github.io/FLAP/type/type_command_line_interface.html#bp-get_cla_list_cli it seems that Ford is trying to document also get_cla_list_cli (but not get_cla_cli), but the docstring of it is missing.

Is it a bug?

Hi again; I am looking at porting a not-so-small code to ford, so
in the process I think I will have some questions/comments...

Here is the first: are abstract interface supported? I see the problem

module m

 implicit none
 public :: i_s

 abstract interface
  subroutine i_s(x)
  !! Define the abstract interface for all the functions used in this
  !! program.
   integer, intent(inout) :: x
  end subroutine i_s
 end interface

end module m

gives

Warning: Error parsing ./src/m.f90.
    'NoneType' object has no attribute 'lower'