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