vacumm / sphinx-fortran Goto Github PK
View Code? Open in Web Editor NEWFortran domain and autodoc extensions to Sphinx
License: Other
Fortran domain and autodoc extensions to Sphinx
License: Other
An argument of a subroutine declared as
DOUBLE PRECISION,DIMENSION(:,:),INTENT(IN):: MYVAR
appears as
re_fieldname_match = re.compile( r'(?P<type>\b\w+\b(?P<kind>\s*\(.*\))?)?\s*(?P<name>\b\w+\b)\s*(?P<shape>\(.*\))?\s*(?P<sattrs>\[.+\])?').match
print(fieldname)
double precision myvar(,) [in]
precision None double None
myvar (,) double precision in
I'm trying to get a Framework :: Sphinx :: Domain
PyPi classifier approved to help with the Sphinx docs as well as keep the ecosystem more organize and I need to demonstrate interest by having 10 or more project maintainers submit comments about their desire to use the new classifier.
If the maintainer of this project thinks a Framework :: Sphinx :: Domain
would be useful for helping people find the domain as well as help the greater Sphinx ecosystem, please leave a comment on sphinx-doc/sphinx#11562 expressing interest in using the classifier with a link to the package that you maintain to help with the approval process.
Once it gets approved I can come back and submit a PR to add it to the package metadata.
Thanks!
sphinx_fortran uses the packages 'six' and 'numpy' but they are not automatically installed by pip when sphinx-fortran is installed. Attempting to use sphinx_fortran without first manually installing 'six' produces the following error:
Extension error:
Could not import extension sphinxfortran.fortran_domain (exception: No module named 'six')
Similarly, if numpy is missing:
Extension error:
Could not import extension sphinxfortran.fortran_autodoc (exception: No module named 'numpy')
Hello,
when using sphinx-fortran on windows systems, I noticed that the function get_src in module fortran_autodoc.py
was wrongly processing filenames with full path stored in block['from']. On win system, a letter is generally used to identify the storage drive, having a column ':' after this letter. The column is used to get the parent block, as in numpy.f2py.crackfortran.py docstring:
B['from'] --- string showing the 'parents' of the current block
This prevents correct execution of sphinx-fortran on win10 for instance.
I suggest the following new version of the function that fixed the issue in my case :
def get_src(self, block):
"""Get the source lines of the file including this block"""
srcfile = block['from']
if os.name != 'nt' or not os.path.isfile(block['from']):
srcfile = block['from'].split(':')[0]
return self.src[srcfile]
Thanks for your kind attention.
Regards,
P.I.: I cannot use a pull request.
Hi, great project!
Is it possible to have a more complete example on the type and format of the information that can be added to the source code, and that is used by Sphinx-Fortran to build the auto-documentation? i.e. something expanding the information contained in the "Optimize the process" section of this page?
Generic procedures are not detected as functions/subroutines, the same for operator overloading. Any chance it will be implemented? Or maybe I'm doing something wrong?
example:
module class_instrumentalization
...
private
interface run
module procedure run_list, run_obj
end interface
public :: run
...
.. automodule:: extensionmodule
:members:
:undoc-members:
:show-inheritance:
current result:
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?
Hi everyone,
I am trying to use sphinx-fortran to autodoc my fortran code. I am able to get it autodoc comments under programs, modules, functions, subroutines and types but I am unable to get the in-line comments for variables into the documentation. For eg.,
integer, parameter :: dp=kind(1.0d0) ! real*8 type
doesn't produce the comment "real*8 type" under the variable "dp" in the documentation. Am I doing something wrong? Or is this a bug with sphinx-fortran extension?
Thanks,
-Navaneeth
Hi,
I encounter the following exception
Extension error: Handler <function fortran_parse at 0x7f35d1032170> for event 'builder-inited' threw an exception (exception: 'fromsky')
when I try to parse a module with:
.. f:automodule:: psfun_d_serial_mod
if the module contains an abstract interface:
abstract interface
function func (x,k)
use psb_base_mod
implicit none
real(psb_dpk_) :: func
real(psb_dpk_), intent (in) :: x
integer(psb_ipk_), intent(in), optional :: k
end function func
end interface
If the previous code is commented, then the generation of the documentation works as intended.
I am using Sphinx version 3.2.1 and Sphinx_Fortran 1.1.1
Thank you in advance!
Module names that are written in upper case in the fortran code are stored in lower case in self.modules of the F90toRst class.
This means that the module name has to be given in lower case to .. f:automodule:: in order to get found by the format_module method. Passing the module name as it occurs in the fortran code to . f:automodule:: makes the format_module method raise an F90toRstException('Unknown module'), which is quite counter intuitive.
Hi,
please change the following lines of class FortranAutoSrcfileDirective(Directive), method run
if objtype:
objtype = objtype.split(' ,')
with:
if objtype:
objtype = objtype.split(',')
objtype = [o.strip() for o in objtype]
There's a white trailing space in the version from the repo.
I cannot pull my changes, sorry.
Thanks in advance for your kind understanding.
Regards,
Hello sphinx-fortran team,
this is a great and very helpful project!
It seems to me that a subroutine description is not properly read when using autosubroutine in case of a continuation line. The documentation says the description comment is used "if they start immediately after the declaration line." If I break the declaration line and use "&" then the description is not used any more (probably because it is not directly following "subroutine").
for readability I would prefer to break the parameters over multiple lines.
Any chances to fix that easily?
best,
rochus
Hi,
I use the following statement for the fortran documentation:
.. f:subroutine:: f90calceph_getversion_str (version)
.. f:subroutine:: calceph_getversion_str (version) BIND(C)
I receive the following warnings.
calceph.misc.rst:15: WARNING: 4 column based index found. It might be a bug of extensions you use: [('single', u'calceph_getversion_str() (fortran subroutine)', u'f//calceph_getversion_str', u'f//calceph_getversion_str')]
calceph.misc.rst:21: WARNING: 4 column based index found. It might be a bug of extensions you use: [('single', u'f90calceph_getversion_str() (fortran subroutine)', u'f//f90calceph_getversion_str', u'f//f90calceph_getversion_str')]
The documentation looks fine but I receive many similar warnings for my fortran documentation.
How can I remove these warnings ?
Best regards,
I was just playing around with sphinx-python (version 1.0.1) and noticed that the header and inline comments are not extracted when the recursive
keyword precedes a subroutine.
Example:
With this Fortran Code:
recursive SUBROUTINE add_tree_node(current, value)
! Add new tree_node into the tree.
TYPE (tree_node), pointer :: current ! pointer to current tree
REAL :: value ! value of new tree node
IF (.NOT.associated(current)) THEN
allocate(current)
current%value = value
ELSEIF (value < current%value) THEN
CALL add_tree_node(current%left, value)
ELSE
CALL add_tree_node(current%right, value)
END IF
END SUBROUTINE add_tree_node
and sphinx-fortran directive: .. f:autosrcfile:: tree_sort_module.f90
I get this after generating with make text
:
subroutine tree_sort_module/add_tree_node(current, value)
Parameters:
* **current*** [**tree_node**,**pointer**]*
* **value*** [**real**]*
Called from:
"tree_sort"
Once I remove the recursive
keyword, the comments get properly included in the docs:
subroutine tree_sort_module/add_tree_node(current, value)
Add new tree_node into the tree.
Parameters:
* **current*** [**tree_node**,**pointer**]* :: pointer to
current tree
* **value*** [**real**]* :: value of new tree node
Called from:
"add_tree_node()", "tree_sort"
Call to:
"add_tree_node()"
Two different things:
these 2 directives don't give the same result for the subroutine toto
.. f:autosrcfile:: toto.f90
.. f:autosubroutine:: toto
The first one detects correctly the optional argument, the other not.
the .. f:autosrcfile:: command doesn't give an "optional" section in the result for optional argument
test.pdf
Just wanted to say you should consider adding the sphinx-extension topic, https://github.com/topics/sphinx-extension, to the repo so it is easier for others to find on the GitHub ecosystem. There are currently 94 other sphinx extensions that use that topic.
In case Fortran source has two or more types declared in the same file, like so:
module test
implicit none
type foo
integer :: foo
end type foo
type bar
integer :: bar
end type bar
end module test
Python will throw a fatal error during generation of the documentation:
Exception occurred:
File "/path/to/sphinxfortran/fortran_autodoc.py", line 1246, in format_quickaccess
tlist = sorted(self.get_blocklist('types', module))
TypeError: '<' not supported between instances of 'dict' and 'dict'
The issue stems from trying to sort dictionaries using the sorted()
function, which is apparently unsupported. This occurs in format_quickaccess
method, so it's probably better to simply remove the call to sorted()
, and leave this job to get_blocklist
method, where sort
parameter defaults to True
anyway.
Fix will be provided in a PR shortly, for your consideration.
BTW, it would be very cool to be able to omit the autogenerated Quick access section from the output, possibly by introducing additional option to f:autosrcfile
directive, for example :no_quick_access:
. I can probably try to prepare this, but I wanted first to check if you accept these kind of enhancements via PRs and if the project is still alive?
Thanks for this great plugin, it's quite unique :)
How can I document a type-bound procedure with sphinx-fortran? Suppose I had the code
module mymod
type foo
real :: a
contains
subroutine do_stuff
end type foo
contains
subroutine do_stuff(self)
class(foo) :: self
print *,self%a
end subroutine do_stuff
end module mymod
...then what syntax do I need to use with sphinx-fortran to indicate that the do_stuff subroutine is bound to the foo type?
link to http://sphinx.pocoo.org/ is broken
Running sphinx with fortran_autodoc on an empty module fails at
parsing fortran sources...{}
Exception occurred:
File ".../sphinx-fortran/sphinxfortran/fortran_autodoc.py", line 347, in scan
m = block['vardescsearch'](line)
KeyError: 'vardescsearch'
Quick fix: add a check if 'vardescsearch' in block.keys():
before line 347 in fortran_autodoc.py
. A better solution would be to unify the initialization of block
for all cases.
When trying to build documentation, the following line raises an Exception:
tlist = sorted(self.get_blocklist('types', module))
... due to trying to sort incompatible types (dictionaries in this case). I have attached the full "Read The Docs" build log, including Traceback:
Why in https://github.com/VACUMM/sphinx-fortran/blob/master/sphinxfortran/fortran_autodoc.py#L1674, do you lowercase the filename of source files ?
My source filenames contain upper letter and consequently your subroutine failed to scan them.
Can you remove this line and the equivalent in the other methods like https://github.com/VACUMM/sphinx-fortran/blob/master/sphinxfortran/fortran_autodoc.py#L1635
Thanks in advance !!!
What about a transition to python3? ;-)
Hi,
I need to mock out numpy to prevent compilation of fortran code, when building my doc by sphinx on ReadTheDocs.
I'm afraid this becomes an issue when this sphinx extension is used, because the extension itself calls f2py (part of numpy).
I'd like to have a return from main developers, if possible.
Many thanks in advance for the kind support.
Hello,
Is it possible to leave the comment header of fortran blocks as raw text without interpreting it as ReST please ?
A possible fix is adding the following lines,
if len(block['desc']) and raw_desc > 0:
block['desc'] = ["! .. code-block::\n"] + block['desc']
right after,
# Comment
block['desc'] = self.get_comment(subsrc, aslist=True)
in the function scan_container of file fortran_autodoc.f90
. The new variable raw_desc should be True if such option was selected when processing the fortran blocks.
Or perhaps, is there another way of achiving this behavior?
Thanks in advance for your kind attention.
Hi,
I am trying to set a minimal working example for fortran_autodoc. make html
works when no files are added to the project. If I add a simple file such as:
module constants
implicit none
real, parameter :: pi = 3.1415926536
real, parameter :: e = 2.7182818285
contains
subroutine show_consts()
print*, "Pi = ", pi
print*, "e = ", e
end subroutine show_consts
end module constants
The file name is test.f90
and it is picked up by conf.py
. I get the following error:
Handler <function fortran_parse at 0x00000166EC1CFCA8> for event 'builder-inited' threw an exception (exception: 'C')
I tried with the test files in the repository as well but I always get the same problem. This is independent to referring to them in index.rst
. I imagine it is something to do with my setup, but I didn't find the traceback helpful at all. Perhaps somebody has come across it before?
Many thanks for your help.
When I try to use fortran_autodoc on a source file that uses an abstract interface, sphinx crashes with
Extension error:
Handler <function fortran_parse at 0x112981d30> for event 'builder-inited' threw an exception (exception: crackline: groupcounter(=0) is nonpositive. Check the blocks.)
make: *** [html] Error 2
Example Fortran source file:
module test
abstract interface
end interface
end module test
Hi,
I noticed the following warning at build:
WARNING: The config value fortran_src' has type
list', defaults to `str'.
Please, change the line (setup function in fortran_autodoc module):
app.add_config_value('fortran_src', '.', False)
to:
app.add_config_value('fortran_src', ['.'], False)
.. note:: I cannot commit/push - sorry.
Thanks in advance.
Regards.
I have a section in a module of my Fortran code where
...
INTEGER, PARAMETER :: ps = 6 !Number of digits of a single precision float
INTEGER, PARAMETER :: rs = 37 !Exponent range of a single precision float
INTEGER, PARAMETER :: pd = 12 !Number of digits of a double precision float
INTEGER, PARAMETER :: rd = 307 !Exponent range of a doble precision float
INTEGER, PARAMETER :: sp = selected_real_kind(ps, rs) !Single precision float kind
INTEGER, PARAMETER :: dp = selected_real_kind(pd, rd) !Double precision float kind
INTEGER, PARAMETER :: qp = selected_real_kind(32) !Quadruple precision float kind
INTEGER, PARAMETER :: wp = dp !Working precision float kind
...
When the autodocumentation is generated for this module, the description for qp is missing and dp is described as "Working precision float kind" as if the comment for wp
corresponded to dp
. Is there a workaround other than writing
...
INTEGER, PARAMETER :: ps = 6 !Number of digits of a single precision float
INTEGER, PARAMETER :: rs = 37 !Exponent range of a single precision float
INTEGER, PARAMETER :: pd = 12 !Number of digits of a double precision float
INTEGER, PARAMETER :: rd = 307 !Exponent range of a doble precision float
INTEGER, PARAMETER :: sp = selected_real_kind(ps, rs) !Single precision float kind
INTEGER, PARAMETER :: dp = selected_real_kind(pd, rd) !Double precision float kind
INTEGER, PARAMETER :: qp & !Quadruple precision float kind
& = selected_real_kind(32)
INTEGER, PARAMETER :: wp & !Working precision float kind: ``dp``
& = dp
...
Dear developers,
I encountered a error when I was making a document:
File "~/.pyenv/versions/anaconda3-2019.10/lib/python3.7/site-packages/sphinxfortran/fortran_autodoc.py", line 348, in scan
m = block'vardescsearch'
KeyError: 'vardescsearch'
I have solved the error by changing the following lines in fortran_autodoc.py:
line 348
if line.strip().startswith('!'):
continue
m = block'vardescsearch'
if m:
block['vars'][m.group('varname').lower()]['desc'] = m.group('vardesc')
to
if line.strip().startswith('!'):
continue
if 'vardescsearch' in block:
m = block'vardescsearch'
if m:
block['vars'][m.group('varname').lower()]['desc'] = m.group('vardesc')
Also, in the user manual, I wonder
.. f:autovariable:: modname
instead,
.. f:automodule:: modname
Best regards.
PC configuration:
OS ubuntu 16.04
I read some blogs about it includes:
google groups(https://groups.google.com/forum/#!topic/sphinx-users/gQfMxDsXQo0)
read the file(https://sphinx-fortran.readthedocs.io/en/latest/)
and related GitHub
I found it hasn't update for a while, is it still compatible with the new version's sphinx?
It is because I cannot import extensions like sphinxfortran.fortran_domain, sphinxfortran.fortran_autodoc in conf.py
the error message is:
Running Sphinx v2.1.2
Extension error:
Could not import extension sphinxfortran.fortran_autodoc (exception: cannot import name 'Directive' from 'sphinx.directives' (unknown location))
Running Sphinx v2.1.2
Extension error:
Could not import extension sphinxfortran.fortran_domain (exception: cannot import name 'Directive' from 'sphinx.util.compat' (/home/tianli/anaconda3/lib/python3.7/site-packages/sphinx/util/compat.py))
In a module i have
...
INTEGER, PARAMETER :: ps = 6 !Number of digits of a single precision float
INTEGER, PARAMETER :: rs = 37 !Exponent range of a single precision float
INTEGER, PARAMETER :: pd = 12 !Number of digits of a double precision float
INTEGER, PARAMETER :: rd = 307 !Exponent range of a doble precision float
INTEGER, PARAMETER :: sp = selected_real_kind(ps, rs) !Single precision float kind
INTEGER, PARAMETER :: dp = selected_real_kind(pd, rd) !Double precision float kind
INTEGER, PARAMETER :: qp & !Quadruple precision float kind
& = selected_real_kind(32)
INTEGER, PARAMETER :: wp & !Working precision float kind: ``dp``
& = dp
#ifdef __MIXED_PRECISION
INTEGER, PARAMETER :: vp & !Mixed precision float kind: ``sp`` or ``dp`` (at compile time)
& = sp !Single precision float kind
#else
INTEGER, PARAMETER :: vp & !Mixed precision float kind: ``sp`` or ``dp`` (at compile time)
& = dp !Double precision float kind
#endif
INTEGER, PARAMETER :: pi1 = 2 !Number of digits of a 1-byte integer
INTEGER, PARAMETER :: pi2 = 4 !Number of digits of a 2-byte integer
INTEGER, PARAMETER :: pi4 = 9 !Number of digits of a 4-byte integer
INTEGER, PARAMETER :: pi8 = 14 !Number of digits of a 8-byte integer
INTEGER, PARAMETER :: i1 & !1-byte integer kind
& = selected_int_kind(pi1)
INTEGER, PARAMETER :: i2 & !2-byte integer kind
& = selected_int_kind(pi2)
INTEGER, PARAMETER :: i4 & !4-byte integer kind
& = selected_int_kind(pi4)
INTEGER, PARAMETER :: i8 & !8-byte integer kind
& = selected_int_kind(pi8)
INTEGER, PARAMETER :: wi & !Working integer kind: ``i4``
& = i4 !4-byte integer kind
PUBLIC :: sp, dp, wp, vp, i1, i2, i4, i8
...
where I needed to use the strategy of dividing all the declarations of parameters with line continuation so that the docstring for one parameter does not end up being the description of the parameter after the equal sign.
However, in the generated documentation the "default" values for vp
, wi
and wp
result to be 4, 4 and 8, respectively. Why is that? Why not simply dp
, i4
and dp
.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.