autodoc feature mixes up descriptions

ostueker commented 5 years ago

I'm currently working on some instructional material on using Sphinx for Fortran projects and I noticed that the autodoc feature mixes up the descriptions of parameters.

E.g. when I have the following Fortran code:

subroutine calc_distance (np, nd, pos, i, j, rij, d, d2)
!
!  Calculate Distance vector, scalar distance and trucated distance
!  between atoms i and j.
!  The distance is truncated at pi/2
!
    implicit none
    integer(kind=4),intent(in) :: np                ! number of particles
    integer(kind=4),intent(in) :: nd                ! number of dimensions
    real(kind=8),intent(in),dimension(nd,np) :: pos ! positions
    integer(kind=4),intent(in) :: i                 ! index particle I
    integer(kind=4),intent(in) :: j                 ! index particle J
    real(kind=8),intent(out),dimension(nd) :: rij   ! distance vector
    real(kind=8),intent(out) :: d                   ! distance
    real(kind=8),intent(out) :: d2                  ! trucated distance

    real ( kind = 8 ), parameter :: PI2 = 3.141592653589793D+00 / 2.0D+00

    rij(1:nd) = pos(1:nd,i) - pos(1:nd,j)

    d = sqrt ( sum ( rij(1:nd)**2 ) )

    !  Truncate the distance:
    d2 = min ( d, PI2 )
end subroutine calc_distance

you can see here that the description of nd is just gone and the one of rij shows up next to j. Code is at https://github.com/ostueker/Example_Fortran (file src/sub_calc_distance.f90).

Any idea if maybe I am doing something wrong?

stefraynaud commented 5 years ago

Hi @ostueker

which version do you use ?

ostueker commented 5 years ago

Hi @stefraynaud, I am using the master branch at e61d9a2 (July 12th, 2018; i.e. the latest) with Python 2.7.

RomuloPBenedetti commented 5 years ago

I've workaround it by putting documentation on extra, cleaner definitions, for example:

    !.. |c_esc| replace:: actual c_esc description...
    ! ...
    character(len=1), parameter :: c_end = 'm', c_esc = achar(27)
    character(len=2), parameter :: c_start = c_esc // '['
    ! ...
    private :: c_end     ! |c_end|
    private :: c_esc     ! |c_esc|
    private :: c_start   ! |c_start|
    ! ...

ostueker commented 5 years ago

Thank you Stephane, that commit seems to fix the issue.

However I noticed that sphinx-fortran now needs sphinx >= 1.8 as with 1.7.5 (in my previous env) I got the following error:

reading sources... [ 28%] RefactoringFortranForSphinx                                                                                                                                       
Exception occurred:
  File "build/bdist.linux-x86_64/egg/sphinxfortran/fortran_domain.py", line 595, in handle_signature
    'module', self.env.temp_data.get('f:module'))
AttributeError: 'DirectiveAdapter' object has no attribute 'env'
The full traceback has been saved in /tmp/sphinx-err-6cxcqG.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Makefile:20: recipe for target 'html' failed
make: *** [html] Error 2

But with Sphinx v1.8.2 it works.

stefraynaud commented 5 years ago

Oliver, can you check that it works for you now?

ostueker commented 5 years ago

Thank you, @stefraynaud !

It now works with both sphinx 1.7.5 and 1.8.2 (I haven't tried any other versions).

VACUMM / sphinx-fortran

autodoc feature mixes up descriptions #17