dev-linux
Ivan Maslov
4 years ago
parent
90db529391
commit
db6fdba231
@ -0,0 +1,2 @@
|
|||||||
|
git clean -f -d
|
||||||
|
pause>nul
|
||||||
@ -0,0 +1 @@
|
|||||||
|
pip
|
||||||
@ -0,0 +1,296 @@
|
|||||||
|
autodocsumm: Extended sphinx autodoc including automatic autosummaries
|
||||||
|
Copyright (C) 2016 Philipp S. Sommer
|
||||||
|
|
||||||
|
This program is free software; you can redistribute it and/or modify
|
||||||
|
it under the terms of the GNU General Public License as published by
|
||||||
|
the Free Software Foundation; either version 2 of the License, or
|
||||||
|
(at your option) any later version.
|
||||||
|
|
||||||
|
This program is distributed in the hope that it will be useful,
|
||||||
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||||
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||||
|
GNU General Public License for more details.
|
||||||
|
|
||||||
|
A copy of the GNU General Public License is provided down below.
|
||||||
|
|
||||||
|
|
||||||
|
GNU GENERAL PUBLIC LICENSE
|
||||||
|
Version 2, June 1991
|
||||||
|
|
||||||
|
Copyright (C) 1989, 1991 Free Software Foundation, Inc., <http://fsf.org/>
|
||||||
|
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
||||||
|
Everyone is permitted to copy and distribute verbatim copies
|
||||||
|
of this license document, but changing it is not allowed.
|
||||||
|
|
||||||
|
Preamble
|
||||||
|
|
||||||
|
The licenses for most software are designed to take away your
|
||||||
|
freedom to share and change it. By contrast, the GNU General Public
|
||||||
|
License is intended to guarantee your freedom to share and change free
|
||||||
|
software--to make sure the software is free for all its users. This
|
||||||
|
General Public License applies to most of the Free Software
|
||||||
|
Foundation's software and to any other program whose authors commit to
|
||||||
|
using it. (Some other Free Software Foundation software is covered by
|
||||||
|
the GNU Lesser General Public License instead.) You can apply it to
|
||||||
|
your programs, too.
|
||||||
|
|
||||||
|
When we speak of free software, we are referring to freedom, not
|
||||||
|
price. Our General Public Licenses are designed to make sure that you
|
||||||
|
have the freedom to distribute copies of free software (and charge for
|
||||||
|
this service if you wish), that you receive source code or can get it
|
||||||
|
if you want it, that you can change the software or use pieces of it
|
||||||
|
in new free programs; and that you know you can do these things.
|
||||||
|
|
||||||
|
To protect your rights, we need to make restrictions that forbid
|
||||||
|
anyone to deny you these rights or to ask you to surrender the rights.
|
||||||
|
These restrictions translate to certain responsibilities for you if you
|
||||||
|
distribute copies of the software, or if you modify it.
|
||||||
|
|
||||||
|
For example, if you distribute copies of such a program, whether
|
||||||
|
gratis or for a fee, you must give the recipients all the rights that
|
||||||
|
you have. You must make sure that they, too, receive or can get the
|
||||||
|
source code. And you must show them these terms so they know their
|
||||||
|
rights.
|
||||||
|
|
||||||
|
We protect your rights with two steps: (1) copyright the software, and
|
||||||
|
(2) offer you this license which gives you legal permission to copy,
|
||||||
|
distribute and/or modify the software.
|
||||||
|
|
||||||
|
Also, for each author's protection and ours, we want to make certain
|
||||||
|
that everyone understands that there is no warranty for this free
|
||||||
|
software. If the software is modified by someone else and passed on, we
|
||||||
|
want its recipients to know that what they have is not the original, so
|
||||||
|
that any problems introduced by others will not reflect on the original
|
||||||
|
authors' reputations.
|
||||||
|
|
||||||
|
Finally, any free program is threatened constantly by software
|
||||||
|
patents. We wish to avoid the danger that redistributors of a free
|
||||||
|
program will individually obtain patent licenses, in effect making the
|
||||||
|
program proprietary. To prevent this, we have made it clear that any
|
||||||
|
patent must be licensed for everyone's free use or not licensed at all.
|
||||||
|
|
||||||
|
The precise terms and conditions for copying, distribution and
|
||||||
|
modification follow.
|
||||||
|
|
||||||
|
GNU GENERAL PUBLIC LICENSE
|
||||||
|
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
|
||||||
|
|
||||||
|
0. This License applies to any program or other work which contains
|
||||||
|
a notice placed by the copyright holder saying it may be distributed
|
||||||
|
under the terms of this General Public License. The "Program", below,
|
||||||
|
refers to any such program or work, and a "work based on the Program"
|
||||||
|
means either the Program or any derivative work under copyright law:
|
||||||
|
that is to say, a work containing the Program or a portion of it,
|
||||||
|
either verbatim or with modifications and/or translated into another
|
||||||
|
language. (Hereinafter, translation is included without limitation in
|
||||||
|
the term "modification".) Each licensee is addressed as "you".
|
||||||
|
|
||||||
|
Activities other than copying, distribution and modification are not
|
||||||
|
covered by this License; they are outside its scope. The act of
|
||||||
|
running the Program is not restricted, and the output from the Program
|
||||||
|
is covered only if its contents constitute a work based on the
|
||||||
|
Program (independent of having been made by running the Program).
|
||||||
|
Whether that is true depends on what the Program does.
|
||||||
|
|
||||||
|
1. You may copy and distribute verbatim copies of the Program's
|
||||||
|
source code as you receive it, in any medium, provided that you
|
||||||
|
conspicuously and appropriately publish on each copy an appropriate
|
||||||
|
copyright notice and disclaimer of warranty; keep intact all the
|
||||||
|
notices that refer to this License and to the absence of any warranty;
|
||||||
|
and give any other recipients of the Program a copy of this License
|
||||||
|
along with the Program.
|
||||||
|
|
||||||
|
You may charge a fee for the physical act of transferring a copy, and
|
||||||
|
you may at your option offer warranty protection in exchange for a fee.
|
||||||
|
|
||||||
|
2. You may modify your copy or copies of the Program or any portion
|
||||||
|
of it, thus forming a work based on the Program, and copy and
|
||||||
|
distribute such modifications or work under the terms of Section 1
|
||||||
|
above, provided that you also meet all of these conditions:
|
||||||
|
|
||||||
|
a) You must cause the modified files to carry prominent notices
|
||||||
|
stating that you changed the files and the date of any change.
|
||||||
|
|
||||||
|
b) You must cause any work that you distribute or publish, that in
|
||||||
|
whole or in part contains or is derived from the Program or any
|
||||||
|
part thereof, to be licensed as a whole at no charge to all third
|
||||||
|
parties under the terms of this License.
|
||||||
|
|
||||||
|
c) If the modified program normally reads commands interactively
|
||||||
|
when run, you must cause it, when started running for such
|
||||||
|
interactive use in the most ordinary way, to print or display an
|
||||||
|
announcement including an appropriate copyright notice and a
|
||||||
|
notice that there is no warranty (or else, saying that you provide
|
||||||
|
a warranty) and that users may redistribute the program under
|
||||||
|
these conditions, and telling the user how to view a copy of this
|
||||||
|
License. (Exception: if the Program itself is interactive but
|
||||||
|
does not normally print such an announcement, your work based on
|
||||||
|
the Program is not required to print an announcement.)
|
||||||
|
|
||||||
|
These requirements apply to the modified work as a whole. If
|
||||||
|
identifiable sections of that work are not derived from the Program,
|
||||||
|
and can be reasonably considered independent and separate works in
|
||||||
|
themselves, then this License, and its terms, do not apply to those
|
||||||
|
sections when you distribute them as separate works. But when you
|
||||||
|
distribute the same sections as part of a whole which is a work based
|
||||||
|
on the Program, the distribution of the whole must be on the terms of
|
||||||
|
this License, whose permissions for other licensees extend to the
|
||||||
|
entire whole, and thus to each and every part regardless of who wrote it.
|
||||||
|
|
||||||
|
Thus, it is not the intent of this section to claim rights or contest
|
||||||
|
your rights to work written entirely by you; rather, the intent is to
|
||||||
|
exercise the right to control the distribution of derivative or
|
||||||
|
collective works based on the Program.
|
||||||
|
|
||||||
|
In addition, mere aggregation of another work not based on the Program
|
||||||
|
with the Program (or with a work based on the Program) on a volume of
|
||||||
|
a storage or distribution medium does not bring the other work under
|
||||||
|
the scope of this License.
|
||||||
|
|
||||||
|
3. You may copy and distribute the Program (or a work based on it,
|
||||||
|
under Section 2) in object code or executable form under the terms of
|
||||||
|
Sections 1 and 2 above provided that you also do one of the following:
|
||||||
|
|
||||||
|
a) Accompany it with the complete corresponding machine-readable
|
||||||
|
source code, which must be distributed under the terms of Sections
|
||||||
|
1 and 2 above on a medium customarily used for software interchange; or,
|
||||||
|
|
||||||
|
b) Accompany it with a written offer, valid for at least three
|
||||||
|
years, to give any third party, for a charge no more than your
|
||||||
|
cost of physically performing source distribution, a complete
|
||||||
|
machine-readable copy of the corresponding source code, to be
|
||||||
|
distributed under the terms of Sections 1 and 2 above on a medium
|
||||||
|
customarily used for software interchange; or,
|
||||||
|
|
||||||
|
c) Accompany it with the information you received as to the offer
|
||||||
|
to distribute corresponding source code. (This alternative is
|
||||||
|
allowed only for noncommercial distribution and only if you
|
||||||
|
received the program in object code or executable form with such
|
||||||
|
an offer, in accord with Subsection b above.)
|
||||||
|
|
||||||
|
The source code for a work means the preferred form of the work for
|
||||||
|
making modifications to it. For an executable work, complete source
|
||||||
|
code means all the source code for all modules it contains, plus any
|
||||||
|
associated interface definition files, plus the scripts used to
|
||||||
|
control compilation and installation of the executable. However, as a
|
||||||
|
special exception, the source code distributed need not include
|
||||||
|
anything that is normally distributed (in either source or binary
|
||||||
|
form) with the major components (compiler, kernel, and so on) of the
|
||||||
|
operating system on which the executable runs, unless that component
|
||||||
|
itself accompanies the executable.
|
||||||
|
|
||||||
|
If distribution of executable or object code is made by offering
|
||||||
|
access to copy from a designated place, then offering equivalent
|
||||||
|
access to copy the source code from the same place counts as
|
||||||
|
distribution of the source code, even though third parties are not
|
||||||
|
compelled to copy the source along with the object code.
|
||||||
|
|
||||||
|
4. You may not copy, modify, sublicense, or distribute the Program
|
||||||
|
except as expressly provided under this License. Any attempt
|
||||||
|
otherwise to copy, modify, sublicense or distribute the Program is
|
||||||
|
void, and will automatically terminate your rights under this License.
|
||||||
|
However, parties who have received copies, or rights, from you under
|
||||||
|
this License will not have their licenses terminated so long as such
|
||||||
|
parties remain in full compliance.
|
||||||
|
|
||||||
|
5. You are not required to accept this License, since you have not
|
||||||
|
signed it. However, nothing else grants you permission to modify or
|
||||||
|
distribute the Program or its derivative works. These actions are
|
||||||
|
prohibited by law if you do not accept this License. Therefore, by
|
||||||
|
modifying or distributing the Program (or any work based on the
|
||||||
|
Program), you indicate your acceptance of this License to do so, and
|
||||||
|
all its terms and conditions for copying, distributing or modifying
|
||||||
|
the Program or works based on it.
|
||||||
|
|
||||||
|
6. Each time you redistribute the Program (or any work based on the
|
||||||
|
Program), the recipient automatically receives a license from the
|
||||||
|
original licensor to copy, distribute or modify the Program subject to
|
||||||
|
these terms and conditions. You may not impose any further
|
||||||
|
restrictions on the recipients' exercise of the rights granted herein.
|
||||||
|
You are not responsible for enforcing compliance by third parties to
|
||||||
|
this License.
|
||||||
|
|
||||||
|
7. If, as a consequence of a court judgment or allegation of patent
|
||||||
|
infringement or for any other reason (not limited to patent issues),
|
||||||
|
conditions are imposed on you (whether by court order, agreement or
|
||||||
|
otherwise) that contradict the conditions of this License, they do not
|
||||||
|
excuse you from the conditions of this License. If you cannot
|
||||||
|
distribute so as to satisfy simultaneously your obligations under this
|
||||||
|
License and any other pertinent obligations, then as a consequence you
|
||||||
|
may not distribute the Program at all. For example, if a patent
|
||||||
|
license would not permit royalty-free redistribution of the Program by
|
||||||
|
all those who receive copies directly or indirectly through you, then
|
||||||
|
the only way you could satisfy both it and this License would be to
|
||||||
|
refrain entirely from distribution of the Program.
|
||||||
|
|
||||||
|
If any portion of this section is held invalid or unenforceable under
|
||||||
|
any particular circumstance, the balance of the section is intended to
|
||||||
|
apply and the section as a whole is intended to apply in other
|
||||||
|
circumstances.
|
||||||
|
|
||||||
|
It is not the purpose of this section to induce you to infringe any
|
||||||
|
patents or other property right claims or to contest validity of any
|
||||||
|
such claims; this section has the sole purpose of protecting the
|
||||||
|
integrity of the free software distribution system, which is
|
||||||
|
implemented by public license practices. Many people have made
|
||||||
|
generous contributions to the wide range of software distributed
|
||||||
|
through that system in reliance on consistent application of that
|
||||||
|
system; it is up to the author/donor to decide if he or she is willing
|
||||||
|
to distribute software through any other system and a licensee cannot
|
||||||
|
impose that choice.
|
||||||
|
|
||||||
|
This section is intended to make thoroughly clear what is believed to
|
||||||
|
be a consequence of the rest of this License.
|
||||||
|
|
||||||
|
8. If the distribution and/or use of the Program is restricted in
|
||||||
|
certain countries either by patents or by copyrighted interfaces, the
|
||||||
|
original copyright holder who places the Program under this License
|
||||||
|
may add an explicit geographical distribution limitation excluding
|
||||||
|
those countries, so that distribution is permitted only in or among
|
||||||
|
countries not thus excluded. In such case, this License incorporates
|
||||||
|
the limitation as if written in the body of this License.
|
||||||
|
|
||||||
|
9. The Free Software Foundation may publish revised and/or new versions
|
||||||
|
of the General Public License from time to time. Such new versions will
|
||||||
|
be similar in spirit to the present version, but may differ in detail to
|
||||||
|
address new problems or concerns.
|
||||||
|
|
||||||
|
Each version is given a distinguishing version number. If the Program
|
||||||
|
specifies a version number of this License which applies to it and "any
|
||||||
|
later version", you have the option of following the terms and conditions
|
||||||
|
either of that version or of any later version published by the Free
|
||||||
|
Software Foundation. If the Program does not specify a version number of
|
||||||
|
this License, you may choose any version ever published by the Free Software
|
||||||
|
Foundation.
|
||||||
|
|
||||||
|
10. If you wish to incorporate parts of the Program into other free
|
||||||
|
programs whose distribution conditions are different, write to the author
|
||||||
|
to ask for permission. For software which is copyrighted by the Free
|
||||||
|
Software Foundation, write to the Free Software Foundation; we sometimes
|
||||||
|
make exceptions for this. Our decision will be guided by the two goals
|
||||||
|
of preserving the free status of all derivatives of our free software and
|
||||||
|
of promoting the sharing and reuse of software generally.
|
||||||
|
|
||||||
|
NO WARRANTY
|
||||||
|
|
||||||
|
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
|
||||||
|
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
|
||||||
|
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
|
||||||
|
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
|
||||||
|
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
||||||
|
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
|
||||||
|
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
|
||||||
|
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
|
||||||
|
REPAIR OR CORRECTION.
|
||||||
|
|
||||||
|
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
|
||||||
|
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
|
||||||
|
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
|
||||||
|
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
|
||||||
|
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
|
||||||
|
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
|
||||||
|
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
|
||||||
|
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
|
||||||
|
POSSIBILITY OF SUCH DAMAGES.
|
||||||
|
|
||||||
|
END OF TERMS AND CONDITIONS
|
||||||
@ -0,0 +1,152 @@
|
|||||||
|
Metadata-Version: 2.1
|
||||||
|
Name: autodocsumm
|
||||||
|
Version: 0.2.2
|
||||||
|
Summary: Extended sphinx autodoc including automatic autosummaries
|
||||||
|
Home-page: https://github.com/Chilipp/autodocsumm
|
||||||
|
Author: Philipp S. Sommer
|
||||||
|
Author-email: philipp.sommer@hzg.de
|
||||||
|
License: GPLv2
|
||||||
|
Keywords: sphinx autodoc autosummary content table
|
||||||
|
Platform: UNKNOWN
|
||||||
|
Classifier: Development Status :: 5 - Production/Stable
|
||||||
|
Classifier: Intended Audience :: Developers
|
||||||
|
Classifier: Topic :: Documentation
|
||||||
|
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
|
||||||
|
Classifier: Programming Language :: Python :: 3
|
||||||
|
Classifier: Programming Language :: Python :: 3 :: Only
|
||||||
|
Classifier: Programming Language :: Python :: 3.5
|
||||||
|
Classifier: Programming Language :: Python :: 3.6
|
||||||
|
Classifier: Programming Language :: Python :: 3.7
|
||||||
|
Classifier: Programming Language :: Python :: 3.8
|
||||||
|
Classifier: Operating System :: OS Independent
|
||||||
|
Requires-Python: >=3.5
|
||||||
|
Description-Content-Type: text/x-rst
|
||||||
|
Requires-Dist: sphinx (>=2.2)
|
||||||
|
|
||||||
|
==============================================
|
||||||
|
Extending your autodoc API docs with a summary
|
||||||
|
==============================================
|
||||||
|
|
||||||
|
.. start-badges
|
||||||
|
|
||||||
|
.. list-table::
|
||||||
|
:stub-columns: 1
|
||||||
|
:widths: 10 90
|
||||||
|
|
||||||
|
* - docs
|
||||||
|
- |docs|
|
||||||
|
* - tests
|
||||||
|
- |github-action| |requires| |codecov|
|
||||||
|
* - package
|
||||||
|
- |version| |supported-versions| |supported-implementations|
|
||||||
|
|
||||||
|
.. |docs| image:: http://readthedocs.org/projects/autodocsumm/badge/?version=latest
|
||||||
|
:alt: Documentation Status
|
||||||
|
:target: http://autodocsumm.readthedocs.io/en/latest/?badge=latest
|
||||||
|
|
||||||
|
.. |github-action| image:: https://github.com/Chilipp/autodocsumm/workflows/Tests/badge.svg
|
||||||
|
:alt: Tests
|
||||||
|
:target: https://github.com/Chilipp/autodocsumm/actions?query=workflow%3A%22Tests%22
|
||||||
|
|
||||||
|
.. |codecov| image:: https://codecov.io/gh/Chilipp/autodocsumm/branch/master/graph/badge.svg?token=I9wlZyhI4Y
|
||||||
|
:alt: Codecov
|
||||||
|
:target: https://codecov.io/gh/Chilipp/autodocsumm
|
||||||
|
|
||||||
|
.. |requires| image:: https://requires.io/github/Chilipp/autodocsumm/requirements.svg?branch=master
|
||||||
|
:alt: Requirements Status
|
||||||
|
:target: https://requires.io/github/Chilipp/autodocsumm/requirements/?branch=master
|
||||||
|
|
||||||
|
.. |version| image:: https://img.shields.io/pypi/v/autodocsumm.svg?style=flat
|
||||||
|
:alt: PyPI Package latest release
|
||||||
|
:target: https://pypi.python.org/pypi/autodocsumm
|
||||||
|
|
||||||
|
.. |supported-versions| image:: https://img.shields.io/pypi/pyversions/autodocsumm.svg?style=flat
|
||||||
|
:alt: Supported versions
|
||||||
|
:target: https://pypi.python.org/pypi/autodocsumm
|
||||||
|
|
||||||
|
.. |supported-implementations| image:: https://img.shields.io/pypi/implementation/autodocsumm.svg?style=flat
|
||||||
|
:alt: Supported implementations
|
||||||
|
:target: https://pypi.python.org/pypi/autodocsumm
|
||||||
|
|
||||||
|
|
||||||
|
.. end-badges
|
||||||
|
|
||||||
|
Welcome! This sphinx extension provides some useful extensions to the Sphinxs
|
||||||
|
autodoc_ extension. Those are
|
||||||
|
|
||||||
|
1. It creates a *Table of Contents* in the style of the autosummary_ extension
|
||||||
|
with methods, classes, functions and attributes
|
||||||
|
2. As you can include the ``__init__`` method documentation for via the
|
||||||
|
autoclass_content_ configuration value,
|
||||||
|
we provide the *autodata_content* configuration value to include
|
||||||
|
the documentation from the ``__call__`` method
|
||||||
|
3. You can exclude the string representation of specific objects. E.g. if you
|
||||||
|
have a large dictionary using the *not_document_data* configuration
|
||||||
|
value.
|
||||||
|
|
||||||
|
See the `Documentation on Readthedocs`_ for more details.
|
||||||
|
|
||||||
|
.. _autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html
|
||||||
|
.. _autoclass_content: http://www.sphinx-doc.org/en/stable/ext/autodoc.html#confval-autoclass_content
|
||||||
|
.. _autosummary: http://www.sphinx-doc.org/en/stable/ext/autosummary.html
|
||||||
|
.. _Documentation on Readthedocs: http://autodocsumm.readthedocs.io/en/latest/
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Installation
|
||||||
|
============
|
||||||
|
Simply install it via ``pip``::
|
||||||
|
|
||||||
|
$ pip install autodocsumm
|
||||||
|
|
||||||
|
Or you install it via::
|
||||||
|
|
||||||
|
$ python setup.py install
|
||||||
|
|
||||||
|
from the `source on GitHub`_.
|
||||||
|
|
||||||
|
|
||||||
|
.. _source on GitHub: https://github.com/Chilipp/autodocsumm
|
||||||
|
|
||||||
|
|
||||||
|
Requirements
|
||||||
|
============
|
||||||
|
The package only requires Sphinx_ to be installed. It has been tested for
|
||||||
|
versions higher than 1.3.
|
||||||
|
|
||||||
|
|
||||||
|
.. _Sphinx: http://www.sphinx-doc.org/en/stable
|
||||||
|
|
||||||
|
|
||||||
|
Quickstart
|
||||||
|
==========
|
||||||
|
|
||||||
|
In order to activate the autodocsumm extension, you have to list it in your
|
||||||
|
``conf.py``:
|
||||||
|
|
||||||
|
.. code-block:: python
|
||||||
|
|
||||||
|
extensions = [
|
||||||
|
'sphinx.ext.autodoc',
|
||||||
|
...,
|
||||||
|
'autodocsumm',
|
||||||
|
]
|
||||||
|
|
||||||
|
Once this is done, you can use the ``:autosummary:`` option for autodoc
|
||||||
|
directives to generate a table at the top, e.g.:
|
||||||
|
|
||||||
|
.. code-block:: rst
|
||||||
|
|
||||||
|
.. automodule:: my.awesome.module
|
||||||
|
:autosummary:
|
||||||
|
|
||||||
|
Optionally, you can make autodocsumm active by default for all autodoc
|
||||||
|
directives by adding in ``conf.py``:
|
||||||
|
|
||||||
|
.. code-block:: python
|
||||||
|
|
||||||
|
autodoc_default_options = {
|
||||||
|
'autosummary': True,
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
@ -0,0 +1,9 @@
|
|||||||
|
autodocsumm-0.2.2.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
|
||||||
|
autodocsumm-0.2.2.dist-info/LICENSE,sha256=WLQQO5Z-K9uc12rl1muHL61-UaH5GBrY3LTf_fMEjfo,15891
|
||||||
|
autodocsumm-0.2.2.dist-info/METADATA,sha256=kCztIwH9ABvo5uD5RY9y365B14E83ullaMn8eunvoDM,4785
|
||||||
|
autodocsumm-0.2.2.dist-info/RECORD,,
|
||||||
|
autodocsumm-0.2.2.dist-info/REQUESTED,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
||||||
|
autodocsumm-0.2.2.dist-info/WHEEL,sha256=qB97nP5e4MrOsXW5bIU5cUn_KSVr10EV0l-GCHG9qNs,97
|
||||||
|
autodocsumm-0.2.2.dist-info/top_level.txt,sha256=VIQoaZCC9b6NgOP48LVPFMwDTy5v5K9xdTGcnxOZHqE,12
|
||||||
|
autodocsumm/__init__.py,sha256=Szc-cITgeiNgCQ0JoemygPP4JUn_ybfRR6czft5XRQw,22233
|
||||||
|
autodocsumm/__pycache__/__init__.cpython-37.pyc,,
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
Wheel-Version: 1.0
|
||||||
|
Generator: bdist_wheel (0.33.1)
|
||||||
|
Root-Is-Purelib: true
|
||||||
|
Tag: py3-none-any
|
||||||
|
|
||||||
@ -0,0 +1 @@
|
|||||||
|
autodocsumm
|
||||||
@ -0,0 +1,587 @@
|
|||||||
|
"""Sphinx extension that defines new auto documenters with autosummary.
|
||||||
|
|
||||||
|
The :class:`AutoSummModuleDocumenter` and :class:`AutoSummClassDocumenter`
|
||||||
|
classes defined here enable an autosummary-style listing of the corresponding
|
||||||
|
members.
|
||||||
|
|
||||||
|
This extension gives also the possibility to choose which data shall be shown
|
||||||
|
and to include the docstring of the ``'__call__'`` attribute.
|
||||||
|
"""
|
||||||
|
from itertools import chain
|
||||||
|
|
||||||
|
from sphinx.util import logging
|
||||||
|
import re
|
||||||
|
|
||||||
|
from docutils import nodes
|
||||||
|
|
||||||
|
import sphinx
|
||||||
|
|
||||||
|
from sphinx.util.docutils import SphinxDirective
|
||||||
|
|
||||||
|
from sphinx.ext.autodoc import (
|
||||||
|
ClassDocumenter, ModuleDocumenter, ALL, PycodeError,
|
||||||
|
ModuleAnalyzer, bool_option, AttributeDocumenter, DataDocumenter, Options,
|
||||||
|
prepare_docstring)
|
||||||
|
import sphinx.ext.autodoc as ad
|
||||||
|
|
||||||
|
signature = Signature = None
|
||||||
|
|
||||||
|
from sphinx.ext.autodoc.directive import (
|
||||||
|
AutodocDirective, AUTODOC_DEFAULT_OPTIONS, process_documenter_options,
|
||||||
|
DocumenterBridge
|
||||||
|
)
|
||||||
|
|
||||||
|
from sphinx.ext.autodoc import get_documenters
|
||||||
|
|
||||||
|
try:
|
||||||
|
from sphinx.util.inspect import signature, stringify_signature
|
||||||
|
except ImportError:
|
||||||
|
from sphinx.ext.autodoc import Signature
|
||||||
|
|
||||||
|
sphinx_version = list(map(float, re.findall(r'\d+', sphinx.__version__)[:3]))
|
||||||
|
|
||||||
|
from sphinx.util import force_decode
|
||||||
|
|
||||||
|
|
||||||
|
try:
|
||||||
|
from cyordereddict import OrderedDict
|
||||||
|
except ImportError:
|
||||||
|
try:
|
||||||
|
from collections import OrderedDict
|
||||||
|
except ImportError:
|
||||||
|
from ordereddict import OrderedDict
|
||||||
|
|
||||||
|
__version__ = '0.2.2'
|
||||||
|
|
||||||
|
__author__ = "Philipp S. Sommer"
|
||||||
|
|
||||||
|
logger = logging.getLogger(__name__)
|
||||||
|
|
||||||
|
#: Options of the :class:`sphinx.ext.autodoc.ModuleDocumenter` that have an
|
||||||
|
#: effect on the selection of members for the documentation
|
||||||
|
member_options = {
|
||||||
|
'members', 'undoc-members', 'inherited-members', 'exclude-members',
|
||||||
|
'private-members', 'special-members', 'imported-members',
|
||||||
|
'ignore-module-all'}
|
||||||
|
|
||||||
|
|
||||||
|
if signature is not None: # sphinx >= 2.4.0
|
||||||
|
def process_signature(obj):
|
||||||
|
sig = signature(obj)
|
||||||
|
return stringify_signature(sig)
|
||||||
|
elif Signature is not None: # sphinx >= 1.7
|
||||||
|
def process_signature(obj):
|
||||||
|
try:
|
||||||
|
args = Signature(obj).format_args()
|
||||||
|
except TypeError:
|
||||||
|
return None
|
||||||
|
else:
|
||||||
|
args = args.replace('\\', '\\\\')
|
||||||
|
return args
|
||||||
|
|
||||||
|
|
||||||
|
def list_option(option):
|
||||||
|
"""Transform a string to a list by splitting at ;;."""
|
||||||
|
return [s.strip() for s in option.split(";;")]
|
||||||
|
|
||||||
|
|
||||||
|
class AutosummaryDocumenter(object):
|
||||||
|
"""Abstract class for for extending Documenter methods
|
||||||
|
|
||||||
|
This classed is used as a base class for Documenters in order to provide
|
||||||
|
the necessary methods for generating the autosummary."""
|
||||||
|
|
||||||
|
#: List of functions that may filter the members
|
||||||
|
filter_funcs = []
|
||||||
|
|
||||||
|
#: Grouper functions
|
||||||
|
grouper_funcs = []
|
||||||
|
|
||||||
|
def __init__(self):
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def get_grouped_documenters(self, all_members=False):
|
||||||
|
"""Method to return the member documenters
|
||||||
|
|
||||||
|
This method is somewhat like a combination of the
|
||||||
|
:meth:`sphinx.ext.autodoc.ModuleDocumenter.generate` method and the
|
||||||
|
:meth:`sphinx.ext.autodoc.ModuleDocumenter.document_members` method.
|
||||||
|
Hence it initializes this instance by importing the object, etc. and
|
||||||
|
it finds the documenters to use for the autosummary option in the same
|
||||||
|
style as the document_members does it.
|
||||||
|
|
||||||
|
Returns
|
||||||
|
-------
|
||||||
|
dict
|
||||||
|
dictionary whose keys are determined by the :attr:`member_sections`
|
||||||
|
dictionary and whose values are lists of tuples. Each tuple
|
||||||
|
consists of a documenter and a boolean to identify whether a module
|
||||||
|
check should be made describes an attribute or not.
|
||||||
|
|
||||||
|
Notes
|
||||||
|
-----
|
||||||
|
If a :class:`sphinx.ext.autodoc.Documenter.member_order` value is not
|
||||||
|
in the :attr:`member_sections` dictionary, it will be put into an
|
||||||
|
additional `Miscellaneous` section."""
|
||||||
|
use_sections = self.options.autosummary_sections
|
||||||
|
|
||||||
|
self.parse_name()
|
||||||
|
self.import_object()
|
||||||
|
# If there is no real module defined, figure out which to use.
|
||||||
|
# The real module is used in the module analyzer to look up the module
|
||||||
|
# where the attribute documentation would actually be found in.
|
||||||
|
# This is used for situations where you have a module that collects the
|
||||||
|
# functions and classes of internal submodules.
|
||||||
|
self.real_modname = None or self.get_real_modname()
|
||||||
|
|
||||||
|
# try to also get a source code analyzer for attribute docs
|
||||||
|
try:
|
||||||
|
self.analyzer = ModuleAnalyzer.for_module(self.real_modname)
|
||||||
|
# parse right now, to get PycodeErrors on parsing (results will
|
||||||
|
# be cached anyway)
|
||||||
|
self.analyzer.find_attr_docs()
|
||||||
|
except PycodeError as err:
|
||||||
|
logger.debug('[autodocsumm] module analyzer failed: %s', err)
|
||||||
|
# no source file -- e.g. for builtin and C modules
|
||||||
|
self.analyzer = None
|
||||||
|
# at least add the module.__file__ as a dependency
|
||||||
|
if hasattr(self.module, '__file__') and self.module.__file__:
|
||||||
|
self.directive.filename_set.add(self.module.__file__)
|
||||||
|
else:
|
||||||
|
self.directive.filename_set.add(self.analyzer.srcname)
|
||||||
|
|
||||||
|
self.env.temp_data['autodoc:module'] = self.modname
|
||||||
|
if self.objpath:
|
||||||
|
self.env.temp_data['autodoc:class'] = self.objpath[0]
|
||||||
|
|
||||||
|
if not self.options.autosummary_force_inline:
|
||||||
|
docstring = self.get_doc()
|
||||||
|
autodocsumm_directive = '.. auto%ssumm::' % self.objtype
|
||||||
|
for s in chain.from_iterable(docstring):
|
||||||
|
if autodocsumm_directive in s:
|
||||||
|
return {}
|
||||||
|
|
||||||
|
# set the members from the autosummary member options
|
||||||
|
options_save = {}
|
||||||
|
for option in member_options.intersection(self.option_spec):
|
||||||
|
autopt = 'autosummary-' + option
|
||||||
|
if getattr(self.options, autopt):
|
||||||
|
options_save[option] = getattr(self.options, option)
|
||||||
|
self.options[option] = getattr(self.options, autopt)
|
||||||
|
|
||||||
|
want_all = all_members or self.options.inherited_members or \
|
||||||
|
self.options.members is ALL
|
||||||
|
# find out which members are documentable
|
||||||
|
members_check_module, members = self.get_object_members(want_all)
|
||||||
|
|
||||||
|
# remove members given by exclude-members
|
||||||
|
if self.options.exclude_members:
|
||||||
|
members = [(membername, member) for (membername, member) in members
|
||||||
|
if membername not in self.options.exclude_members]
|
||||||
|
|
||||||
|
# document non-skipped members
|
||||||
|
memberdocumenters = []
|
||||||
|
registry = get_documenters(self.env.app)
|
||||||
|
|
||||||
|
for (mname, member, isattr) in self.filter_members(members, want_all):
|
||||||
|
classes = [cls for cls in registry.values()
|
||||||
|
if cls.can_document_member(member, mname, isattr, self)]
|
||||||
|
if not classes:
|
||||||
|
# don't know how to document this member
|
||||||
|
continue
|
||||||
|
# prefer the documenter with the highest priority
|
||||||
|
classes.sort(key=lambda cls: cls.priority)
|
||||||
|
# give explicitly separated module name, so that members
|
||||||
|
# of inner classes can be documented
|
||||||
|
full_mname = self.modname + '::' + \
|
||||||
|
'.'.join(self.objpath + [mname])
|
||||||
|
|
||||||
|
documenter = classes[-1](self.directive, full_mname, self.indent)
|
||||||
|
memberdocumenters.append((documenter,
|
||||||
|
members_check_module and not isattr))
|
||||||
|
|
||||||
|
member_order = (
|
||||||
|
self.options.member_order or self.env.config.autodoc_member_order
|
||||||
|
)
|
||||||
|
try:
|
||||||
|
memberdocumenters = self.sort_members(
|
||||||
|
memberdocumenters, member_order
|
||||||
|
)
|
||||||
|
except AttributeError: # sphinx<3.0
|
||||||
|
pass
|
||||||
|
|
||||||
|
documenters = OrderedDict()
|
||||||
|
for e in memberdocumenters:
|
||||||
|
section = self.member_sections.get(
|
||||||
|
e[0].member_order, 'Miscellaneous')
|
||||||
|
if self.env.app:
|
||||||
|
e[0].parse_name()
|
||||||
|
e[0].import_object()
|
||||||
|
if members_check_module and not e[0].check_module():
|
||||||
|
continue
|
||||||
|
user_section = self.env.app.emit_firstresult(
|
||||||
|
'autodocsumm-grouper', self.objtype, e[0].object_name,
|
||||||
|
e[0].object, section, self.object)
|
||||||
|
section = user_section or section
|
||||||
|
if not use_sections or section in use_sections:
|
||||||
|
documenters.setdefault(section, []).append(e)
|
||||||
|
self.options.update(options_save)
|
||||||
|
return documenters
|
||||||
|
|
||||||
|
def add_autosummary(self):
|
||||||
|
"""Add the autosammary table of this documenter."""
|
||||||
|
if self.options.autosummary:
|
||||||
|
|
||||||
|
grouped_documenters = self.get_grouped_documenters()
|
||||||
|
|
||||||
|
sourcename = self.get_sourcename()
|
||||||
|
|
||||||
|
for section, documenters in grouped_documenters.items():
|
||||||
|
if not self.options.autosummary_no_titles:
|
||||||
|
self.add_line('**%s:**' % section, sourcename)
|
||||||
|
|
||||||
|
self.add_line('', sourcename)
|
||||||
|
|
||||||
|
self.add_line('.. autosummary::', sourcename)
|
||||||
|
self.add_line('', sourcename)
|
||||||
|
indent = ' '
|
||||||
|
|
||||||
|
for (documenter, _) in documenters:
|
||||||
|
self.add_line(
|
||||||
|
indent + '~' + documenter.fullname, sourcename)
|
||||||
|
self.add_line('', sourcename)
|
||||||
|
|
||||||
|
|
||||||
|
class AutoSummModuleDocumenter(ModuleDocumenter, AutosummaryDocumenter):
|
||||||
|
"""Module documentor with autosummary tables of its members.
|
||||||
|
|
||||||
|
This class has the same functionality as the base
|
||||||
|
:class:`sphinx.ext.autodoc.ModuleDocumenter` class but with an additional
|
||||||
|
`autosummary`.
|
||||||
|
It's priority is slightly higher than the one of the ModuleDocumenter.
|
||||||
|
"""
|
||||||
|
|
||||||
|
#: slightly higher priority than
|
||||||
|
#: :class:`sphinx.ext.autodoc.ModuleDocumenter`
|
||||||
|
priority = ModuleDocumenter.priority + 0.1
|
||||||
|
|
||||||
|
#: original option_spec from :class:`sphinx.ext.autodoc.ModuleDocumenter`
|
||||||
|
#: but with additional autosummary boolean option
|
||||||
|
option_spec = ModuleDocumenter.option_spec.copy()
|
||||||
|
option_spec['autosummary'] = bool_option
|
||||||
|
option_spec['autosummary-no-nesting'] = bool_option
|
||||||
|
option_spec['autosummary-sections'] = list_option
|
||||||
|
option_spec['autosummary-no-titles'] = bool_option
|
||||||
|
option_spec['autosummary-force-inline'] = bool_option
|
||||||
|
|
||||||
|
#: Add options for members for the autosummary
|
||||||
|
for _option in member_options.intersection(option_spec):
|
||||||
|
option_spec['autosummary-' + _option] = option_spec[_option]
|
||||||
|
del _option
|
||||||
|
|
||||||
|
member_sections = OrderedDict([
|
||||||
|
(ad.ClassDocumenter.member_order, 'Classes'),
|
||||||
|
(ad.ExceptionDocumenter.member_order, 'Exceptions'),
|
||||||
|
(ad.FunctionDocumenter.member_order, 'Functions'),
|
||||||
|
(ad.DataDocumenter.member_order, 'Data'),
|
||||||
|
])
|
||||||
|
""":class:`~collections.OrderedDict` that includes the autosummary sections
|
||||||
|
|
||||||
|
This dictionary defines the sections for the autosummmary option. The
|
||||||
|
values correspond to the :attr:`sphinx.ext.autodoc.Documenter.member_order`
|
||||||
|
attribute that shall be used for each section."""
|
||||||
|
|
||||||
|
def add_content(self, *args, **kwargs):
|
||||||
|
super().add_content(*args, **kwargs)
|
||||||
|
|
||||||
|
self.add_autosummary()
|
||||||
|
|
||||||
|
if self.options.autosummary_no_nesting:
|
||||||
|
self.options.autosummary = False
|
||||||
|
|
||||||
|
|
||||||
|
class AutoSummClassDocumenter(ClassDocumenter, AutosummaryDocumenter):
|
||||||
|
"""Class documentor with autosummary tables for its members.
|
||||||
|
|
||||||
|
This class has the same functionality as the base
|
||||||
|
:class:`sphinx.ext.autodoc.ClassDocumenter` class but with an additional
|
||||||
|
`autosummary` option to provide the ability to provide a summary of all
|
||||||
|
methods and attributes.
|
||||||
|
It's priority is slightly higher than the one of the ClassDocumenter
|
||||||
|
"""
|
||||||
|
|
||||||
|
#: slightly higher priority than
|
||||||
|
#: :class:`sphinx.ext.autodoc.ClassDocumenter`
|
||||||
|
priority = ClassDocumenter.priority + 0.1
|
||||||
|
|
||||||
|
#: original option_spec from :class:`sphinx.ext.autodoc.ClassDocumenter`
|
||||||
|
#: but with additional autosummary boolean option
|
||||||
|
option_spec = ClassDocumenter.option_spec.copy()
|
||||||
|
option_spec['autosummary'] = bool_option
|
||||||
|
option_spec['autosummary-no-nesting'] = bool_option
|
||||||
|
option_spec['autosummary-sections'] = list_option
|
||||||
|
option_spec['autosummary-no-titles'] = bool_option
|
||||||
|
option_spec['autosummary-force-inline'] = bool_option
|
||||||
|
|
||||||
|
#: Add options for members for the autosummary
|
||||||
|
for _option in member_options.intersection(option_spec):
|
||||||
|
option_spec['autosummary-' + _option] = option_spec[_option]
|
||||||
|
del _option
|
||||||
|
|
||||||
|
member_sections = OrderedDict([
|
||||||
|
(ad.ClassDocumenter.member_order, 'Classes'),
|
||||||
|
(ad.MethodDocumenter.member_order, 'Methods'),
|
||||||
|
(ad.AttributeDocumenter.member_order, 'Attributes'),
|
||||||
|
])
|
||||||
|
""":class:`~collections.OrderedDict` that includes the autosummary sections
|
||||||
|
|
||||||
|
This dictionary defines the sections for the autosummmary option. The
|
||||||
|
values correspond to the :attr:`sphinx.ext.autodoc.Documenter.member_order`
|
||||||
|
attribute that shall be used for each section."""
|
||||||
|
|
||||||
|
def add_content(self, *args, **kwargs):
|
||||||
|
super().add_content(*args, **kwargs)
|
||||||
|
|
||||||
|
self.add_autosummary()
|
||||||
|
|
||||||
|
|
||||||
|
class CallableDataDocumenter(DataDocumenter):
|
||||||
|
""":class:`sphinx.ext.autodoc.DataDocumenter` that uses the __call__ attr
|
||||||
|
"""
|
||||||
|
|
||||||
|
priority = DataDocumenter.priority + 0.1
|
||||||
|
|
||||||
|
def format_args(self):
|
||||||
|
# for classes, the relevant signature is the __init__ method's
|
||||||
|
callmeth = self.get_attr(self.object, '__call__', None)
|
||||||
|
if callmeth is None:
|
||||||
|
return None
|
||||||
|
return process_signature(callmeth)
|
||||||
|
|
||||||
|
def get_doc(self, encoding=None, ignore=1):
|
||||||
|
"""Reimplemented to include data from the call method"""
|
||||||
|
content = self.env.config.autodata_content
|
||||||
|
if content not in ('both', 'call') or not self.get_attr(
|
||||||
|
self.get_attr(self.object, '__call__', None), '__doc__'):
|
||||||
|
return super(CallableDataDocumenter, self).get_doc(
|
||||||
|
encoding=encoding, ignore=ignore)
|
||||||
|
|
||||||
|
# for classes, what the "docstring" is can be controlled via a
|
||||||
|
# config value; the default is both docstrings
|
||||||
|
docstrings = []
|
||||||
|
if content != 'call':
|
||||||
|
docstring = self.get_attr(self.object, '__doc__', None)
|
||||||
|
docstrings = [docstring + '\n'] if docstring else []
|
||||||
|
calldocstring = self.get_attr(
|
||||||
|
self.get_attr(self.object, '__call__', None), '__doc__')
|
||||||
|
if docstrings:
|
||||||
|
docstrings[0] += calldocstring
|
||||||
|
else:
|
||||||
|
docstrings.append(calldocstring + '\n')
|
||||||
|
|
||||||
|
doc = []
|
||||||
|
for docstring in docstrings:
|
||||||
|
if not isinstance(docstring, str):
|
||||||
|
docstring = force_decode(docstring, encoding)
|
||||||
|
doc.append(prepare_docstring(docstring, ignore))
|
||||||
|
|
||||||
|
return doc
|
||||||
|
|
||||||
|
|
||||||
|
class CallableAttributeDocumenter(AttributeDocumenter):
|
||||||
|
""":class:`sphinx.ext.autodoc.AttributeDocumenter` that uses the __call__
|
||||||
|
attr
|
||||||
|
"""
|
||||||
|
|
||||||
|
priority = AttributeDocumenter.priority + 0.1
|
||||||
|
|
||||||
|
def format_args(self):
|
||||||
|
# for classes, the relevant signature is the __init__ method's
|
||||||
|
callmeth = self.get_attr(self.object, '__call__', None)
|
||||||
|
if callmeth is None:
|
||||||
|
return None
|
||||||
|
return process_signature(callmeth)
|
||||||
|
|
||||||
|
def get_doc(self, encoding=None, ignore=1):
|
||||||
|
"""Reimplemented to include data from the call method"""
|
||||||
|
content = self.env.config.autodata_content
|
||||||
|
if content not in ('both', 'call') or not self.get_attr(
|
||||||
|
self.get_attr(self.object, '__call__', None), '__doc__'):
|
||||||
|
return super(CallableAttributeDocumenter, self).get_doc(
|
||||||
|
encoding=encoding, ignore=ignore)
|
||||||
|
|
||||||
|
# for classes, what the "docstring" is can be controlled via a
|
||||||
|
# config value; the default is both docstrings
|
||||||
|
docstrings = []
|
||||||
|
if content != 'call':
|
||||||
|
docstring = self.get_attr(self.object, '__doc__', None)
|
||||||
|
docstrings = [docstring + '\n'] if docstring else []
|
||||||
|
calldocstring = self.get_attr(
|
||||||
|
self.get_attr(self.object, '__call__', None), '__doc__')
|
||||||
|
if docstrings:
|
||||||
|
docstrings[0] += calldocstring
|
||||||
|
else:
|
||||||
|
docstrings.append(calldocstring + '\n')
|
||||||
|
|
||||||
|
doc = []
|
||||||
|
for docstring in docstrings:
|
||||||
|
if not isinstance(docstring, str):
|
||||||
|
docstring = force_decode(docstring, encoding)
|
||||||
|
doc.append(prepare_docstring(docstring, ignore))
|
||||||
|
|
||||||
|
return doc
|
||||||
|
|
||||||
|
|
||||||
|
def dont_document_data(config, fullname):
|
||||||
|
"""Check whether the given object should be documented
|
||||||
|
|
||||||
|
Parameters
|
||||||
|
----------
|
||||||
|
config: sphinx.Options
|
||||||
|
The configuration
|
||||||
|
fullname: str
|
||||||
|
The name of the object
|
||||||
|
|
||||||
|
Returns
|
||||||
|
-------
|
||||||
|
bool
|
||||||
|
Whether the data of `fullname` should be excluded or not"""
|
||||||
|
if config.document_data is True:
|
||||||
|
document_data = [re.compile('.*')]
|
||||||
|
else:
|
||||||
|
document_data = config.document_data
|
||||||
|
if config.not_document_data is True:
|
||||||
|
not_document_data = [re.compile('.*')]
|
||||||
|
else:
|
||||||
|
not_document_data = config.not_document_data
|
||||||
|
return (
|
||||||
|
# data should not be documented
|
||||||
|
(any(re.match(p, fullname) for p in not_document_data)) or
|
||||||
|
# or data is not included in what should be documented
|
||||||
|
(not any(re.match(p, fullname) for p in document_data)))
|
||||||
|
|
||||||
|
|
||||||
|
class NoDataDataDocumenter(CallableDataDocumenter):
|
||||||
|
"""DataDocumenter that prevents the displaying of large data"""
|
||||||
|
|
||||||
|
#: slightly higher priority as the one of the CallableDataDocumenter
|
||||||
|
priority = CallableDataDocumenter.priority + 0.1
|
||||||
|
|
||||||
|
def __init__(self, *args, **kwargs):
|
||||||
|
super(NoDataDataDocumenter, self).__init__(*args, **kwargs)
|
||||||
|
fullname = '.'.join(self.name.rsplit('::', 1))
|
||||||
|
if hasattr(self.env, 'config') and dont_document_data(
|
||||||
|
self.env.config, fullname):
|
||||||
|
self.options = Options(self.options)
|
||||||
|
self.options.annotation = ' '
|
||||||
|
|
||||||
|
|
||||||
|
class NoDataAttributeDocumenter(CallableAttributeDocumenter):
|
||||||
|
"""AttributeDocumenter that prevents the displaying of large data"""
|
||||||
|
|
||||||
|
#: slightly higher priority as the one of the CallableAttributeDocumenter
|
||||||
|
priority = CallableAttributeDocumenter.priority + 0.1
|
||||||
|
|
||||||
|
def __init__(self, *args, **kwargs):
|
||||||
|
super(NoDataAttributeDocumenter, self).__init__(*args, **kwargs)
|
||||||
|
fullname = '.'.join(self.name.rsplit('::', 1))
|
||||||
|
if hasattr(self.env, 'config') and dont_document_data(
|
||||||
|
self.env.config, fullname):
|
||||||
|
self.options = Options(self.options)
|
||||||
|
self.options.annotation = ' '
|
||||||
|
|
||||||
|
|
||||||
|
class AutoDocSummDirective(SphinxDirective):
|
||||||
|
"""A directive to generate an autosummary.
|
||||||
|
|
||||||
|
Usage::
|
||||||
|
|
||||||
|
.. autoclasssum:: <Class>
|
||||||
|
|
||||||
|
.. automodsum:: <module>
|
||||||
|
|
||||||
|
The directive additionally supports all options of the ``autoclass`` or
|
||||||
|
``automod`` directive respectively. Sections can be a list of section titles
|
||||||
|
to be included. If ommitted, all sections are used.
|
||||||
|
"""
|
||||||
|
|
||||||
|
has_content = False
|
||||||
|
|
||||||
|
option_spec = AutodocDirective.option_spec
|
||||||
|
|
||||||
|
required_arguments = 1
|
||||||
|
optional_arguments = 0
|
||||||
|
|
||||||
|
def run(self):
|
||||||
|
reporter = self.state.document.reporter
|
||||||
|
|
||||||
|
try:
|
||||||
|
source, lineno = reporter.get_source_and_line(self.lineno)
|
||||||
|
except AttributeError:
|
||||||
|
source, lineno = (None, None)
|
||||||
|
|
||||||
|
# look up target Documenter
|
||||||
|
objtype = self.name[4:-4] # strip prefix (auto-) and suffix (-summ).
|
||||||
|
doccls = self.env.app.registry.documenters[objtype]
|
||||||
|
|
||||||
|
self.options['autosummary-force-inline'] = True
|
||||||
|
self.options['autosummary'] = True
|
||||||
|
if 'no-members' not in self.options:
|
||||||
|
self.options['members'] = True
|
||||||
|
|
||||||
|
# process the options with the selected documenter's option_spec
|
||||||
|
try:
|
||||||
|
documenter_options = process_documenter_options(doccls, self.config,
|
||||||
|
self.options)
|
||||||
|
except (KeyError, ValueError, TypeError) as exc:
|
||||||
|
# an option is either unknown or has a wrong type
|
||||||
|
logger.error(
|
||||||
|
'An option to %s is either unknown or has an invalid '
|
||||||
|
'value: %s', self.name, exc,
|
||||||
|
location=(self.env.docname, lineno))
|
||||||
|
return []
|
||||||
|
|
||||||
|
# generate the output
|
||||||
|
params = DocumenterBridge(self.env, reporter, documenter_options,
|
||||||
|
lineno, self.state)
|
||||||
|
documenter = doccls(params, self.arguments[0])
|
||||||
|
documenter.add_autosummary()
|
||||||
|
|
||||||
|
node = nodes.paragraph()
|
||||||
|
node.document = self.state.document
|
||||||
|
self.state.nested_parse(params.result, 0, node)
|
||||||
|
|
||||||
|
return node.children
|
||||||
|
|
||||||
|
|
||||||
|
def setup(app):
|
||||||
|
"""setup function for using this module as a sphinx extension"""
|
||||||
|
app.setup_extension('sphinx.ext.autosummary')
|
||||||
|
app.setup_extension('sphinx.ext.autodoc')
|
||||||
|
app.add_directive('autoclasssumm', AutoDocSummDirective)
|
||||||
|
app.add_directive('automodulesumm', AutoDocSummDirective)
|
||||||
|
|
||||||
|
AUTODOC_DEFAULT_OPTIONS.extend(
|
||||||
|
[option for option in AutoSummModuleDocumenter.option_spec
|
||||||
|
if option not in AUTODOC_DEFAULT_OPTIONS])
|
||||||
|
|
||||||
|
AUTODOC_DEFAULT_OPTIONS.extend(
|
||||||
|
[option for option in AutoSummClassDocumenter.option_spec
|
||||||
|
if option not in AUTODOC_DEFAULT_OPTIONS])
|
||||||
|
|
||||||
|
# make sure to allow inheritance when registering new documenters
|
||||||
|
registry = get_documenters(app)
|
||||||
|
for cls in [AutoSummClassDocumenter, AutoSummModuleDocumenter,
|
||||||
|
CallableAttributeDocumenter, NoDataDataDocumenter,
|
||||||
|
NoDataAttributeDocumenter]:
|
||||||
|
if not issubclass(registry.get(cls.objtype), cls):
|
||||||
|
app.add_autodocumenter(cls, override=True)
|
||||||
|
|
||||||
|
# group event
|
||||||
|
app.add_event('autodocsumm-grouper')
|
||||||
|
|
||||||
|
# config value
|
||||||
|
app.add_config_value('autodata_content', 'class', True)
|
||||||
|
app.add_config_value('document_data', True, True)
|
||||||
|
app.add_config_value('not_document_data', [], True)
|
||||||
|
return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
|
||||||
Loading…
Reference in new issue