Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Exceptions in separate section #170

Draft
wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

Exceptions in separate section #170

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b7db5f9
Move exceptions to a separate section
sizmailov Jul 12, 2020
7778fed
Update documentation
sizmailov Jul 12, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion doc/documentation/python.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1162,6 +1162,9 @@ Property Description
`Function properties`_ for details.
:py:`page.methods` List of methods. See
`Function properties`_ for details.
:py:`page.exceptions` List of exceptions, does not overlap
with py:`page.classes`. See
`Class properties`_ for details.
:py:`page.dunder_methods` List of double-underscored special
functions. See
`Function properties`_ for details.
Expand Down Expand Up @@ -1199,6 +1202,7 @@ Property Description
======================================= =======================================
:py:`class_.url` URL of detailed class documentation
:py:`class_.name` Class name
:py:`class_.is_exception` Marks exceptions
:py:`class_.summary` Doc summary
======================================= =======================================

Expand Down Expand Up @@ -1396,7 +1400,8 @@ The form of each list entry is the same:
Property Description
=============================== ===============================================
:py:`i.kind` Entry kind (one of :py:`'module'`,
:py:`'class'` or :py:`'page'`)
:py:`'class'`, :py:`'exception'` or
:py:`'page'`)
:py:`i.name` Name
:py:`i.url` URL of the file with detailed documentation
:py:`i.summary` Doc summary
Expand Down
18 changes: 15 additions & 3 deletions documentation/python.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -398,6 +398,7 @@ def crawl_class(state: State, path: List[str], class_):
class_entry.type = EntryType.CLASS
class_entry.object = class_
class_entry.path = path
class_entry.is_exception = issubclass(class_, BaseException)
class_entry.css_classes = ['m-doc']
class_entry.url = state.config['URL_FORMATTER'](EntryType.CLASS, path)[1]
class_entry.members = []
Expand Down Expand Up @@ -1264,6 +1265,7 @@ def extract_class_doc(state: State, entry: Empty):
out = Empty()
out.url = entry.url
out.name = entry.path[-1]
out.is_exception = entry.is_exception
out.summary = extract_docs(state, state.class_docs, entry.type, entry.path, entry.object.__doc__, summary_only=True)

# Call all scope exit hooks last
Expand Down Expand Up @@ -1913,6 +1915,7 @@ def render_module(state: State, path, module, env):
page.enums = []
page.functions = []
page.data = []
page.exceptions = []
page.has_enum_details = False
page.has_function_details = False
page.has_data_details = False
Expand All @@ -1933,7 +1936,11 @@ def render_module(state: State, path, module, env):
if member_entry.type == EntryType.MODULE:
page.modules += [extract_module_doc(state, member_entry)]
elif member_entry.type == EntryType.CLASS:
page.classes += [extract_class_doc(state, member_entry)]
doc_ = extract_class_doc(state, member_entry)
if doc_.is_exception:
page.exceptions += [doc_]
else:
page.classes += [doc_]
elif member_entry.type == EntryType.ENUM:
enum_ = extract_enum_doc(state, member_entry)
page.enums += [enum_]
Expand Down Expand Up @@ -2004,6 +2011,7 @@ def render_class(state: State, path, class_, env):
page.methods = []
page.properties = []
page.data = []
page.exceptions = []
page.has_enum_details = False
page.has_function_details = False
page.has_property_details = False
Expand All @@ -2024,7 +2032,11 @@ def render_class(state: State, path, class_, env):
logging.warning("%s is undocumented", subpath_str)

if member_entry.type == EntryType.CLASS:
page.classes += [extract_class_doc(state, member_entry)]
doc_ = extract_class_doc(state, member_entry)
if doc_.is_exception:
page.exceptions += [doc_]
else:
page.classes += [doc_]
elif member_entry.type == EntryType.ENUM:
enum_ = extract_enum_doc(state, member_entry)
page.enums += [enum_]
Expand Down Expand Up @@ -2547,7 +2559,7 @@ def path_to_url(path):
# from the top-level index list and gather all class/module children.
def fetch_class_index(entry):
index_entry = Empty()
index_entry.kind = 'module' if entry.type == EntryType.MODULE else 'class'
index_entry.kind = 'module' if entry.type == EntryType.MODULE else ('exception' if entry.is_exception else 'class')
index_entry.name = entry.path[-1]
index_entry.url = state.config['URL_FORMATTER'](entry.type, entry.path)[1]
index_entry.summary = entry.summary
Expand Down
15 changes: 14 additions & 1 deletion documentation/templates/python/class.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@

{% block main %}
<h1>
{%+ for name, target in page.breadcrumb[:-1] %}<span class="m-breadcrumb"><a href="{{ target }}">{{ name }}</a>.<wbr/></span>{% endfor %}{{ page.breadcrumb[-1][0] }} <span class="m-thin">class</span>
{%+ for name, target in page.breadcrumb[:-1] %}<span class="m-breadcrumb"><a href="{{ target }}">{{ name }}</a>.<wbr/></span>{% endfor %}{{ page.breadcrumb[-1][0] }} <span class="m-thin">{% if page.is_exception %}exception{% else %}class{% endif %}</span>
</h1>
{% if page.summary %}
<p>{{ page.summary }}</p>
Expand Down Expand Up @@ -51,6 +51,9 @@ <h3>Contents</h3>
{% if page.data %}
<li><a href="#data">Data</a></li>
{% endif %}
{% if page.exceptions %}
<li><a href="#exceptions">Exceptions</a></li>
{% endif %}
</ul>
</li>
</ul>
Expand Down Expand Up @@ -139,6 +142,16 @@ <h2><a href="#data">Data</a></h2>
</dl>
</section>
{% endif %}
{% if page.exceptions %}
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've created a separate variable for exceptions. The alternatives of has_exceptions/has_classes variables or manual checks in templates look worse to me.

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd actually keep them together in page.classes and branch in the template. That way people have more flexibility, either have them separate or put them sorted together with classes into a single "Classes" section in a modified template if they want.

<section id="exceptions">
<h2><a href="#exceptions">Exceptions</a></h2>
<dl class="m-doc">
{% for exception in page.exceptions %}
{{ entry_class(exception) }}
{% endfor %}
</dl>
</section>
{% endif %}
{% if page.has_enum_details %}
<section>
<h2>Enum documentation</h2>
Expand Down
2 changes: 1 addition & 1 deletion documentation/templates/python/entry-class.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
<dt>class <a href="{{ class.url }}" class="m-doc">{{ class.name }}</a>{% if class.is_deprecated %} <span class="m-label m-danger">deprecated</span>{% endif %}</dt>
<dt>{%if class.is_exception%}exception{%else%}class{%endif%} <a href="{{ class.url }}" class="m-doc">{{ class.name }}</a>{% if class.is_deprecated %} <span class="m-label m-danger">deprecated</span>{% endif %}</dt>
<dd>{{ class.summary }}</dd>
13 changes: 13 additions & 0 deletions documentation/templates/python/module.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,9 @@ <h3>Contents</h3>
{% if page.data %}
<li><a href="#data">Data</a></li>
{% endif %}
{% if page.exceptions %}
<li><a href="#exceptions">Exceptions</a></li>
{% endif %}
</ul>
</li>
</ul>
Expand Down Expand Up @@ -99,6 +102,16 @@ <h2><a href="#data">Data</a></h2>
</dl>
</section>
{% endif %}
{% if page.exceptions %}
<section id="exceptions">
<h2><a href="#exceptions">Exceptions</a></h2>
<dl class="m-doc">
{% for exception in page.exceptions %}
{{ entry_class(exception) }}
{% endfor %}
</dl>
</section>
{% endif %}
{% if page.has_enum_details %}
<section>
<h2>Enum documentation</h2>
Expand Down
8 changes: 7 additions & 1 deletion documentation/test_python/content/classes.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,16 @@ <h1>Classes</h2>
<ul class="m-doc">
<li>module <a href="content.docstring_summary.html" class="m-doc">docstring_summary</a> <span class="m-doc">This module retains summary from the docstring</span></li>
<li>module <a href="content.submodule.html" class="m-doc">submodule</a> <span class="m-doc">This submodule has an external summary.</span></li>
<li>class <a href="content.Class.html" class="m-doc">Class</a> <span class="m-doc">This overwrites the docstring for <a class="m-doc" href="content.Class.html">Class</a>.</span></li>
<li class="m-doc-collapsible collapsed">
<a href="#" onclick="return toggle(this)">class</a> <a href="content.Class.html" class="m-doc">Class</a> <span class="m-doc">This overwrites the docstring for <a class="m-doc" href="content.Class.html">Class</a>.</span>
<ul class="m-doc">
<li>exception <a href="content.Class.ClassError.html" class="m-doc">ClassError</a> <span class="m-doc">This exception belongs to class</span></li>
</ul>
</li>
<li>class <a href="content.ClassDocumentingItsMembers.html" class="m-doc">ClassDocumentingItsMembers</a> <span class="m-doc">This class documents its members directly in its own directive</span></li>
<li>class <a href="content.ClassWithSlots.html" class="m-doc">ClassWithSlots</a> <span class="m-doc">This class has slots and those have to be documented externally</span></li>
<li>class <a href="content.ClassWithSummary.html" class="m-doc">ClassWithSummary</a> <span class="m-doc">This class has summary from the docstring</span></li>
<li>exception <a href="content.FreeStandingError.html" class="m-doc">FreeStandingError</a> <span class="m-doc">This exception belongs to module</span></li>
</ul>
</li>
</ul>
Expand Down
8 changes: 8 additions & 0 deletions documentation/test_python/content/content.Class.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ <h3>Contents</h3>
<li><a href="#dunder-methods">Special methods</a></li>
<li><a href="#properties">Properties</a></li>
<li><a href="#data">Data</a></li>
<li><a href="#exceptions">Exceptions</a></li>
</ul>
</li>
</ul>
Expand Down Expand Up @@ -122,6 +123,13 @@ <h2><a href="#data">Data</a></h2>
<dd></dd>
</dl>
</section>
<section id="exceptions">
<h2><a href="#exceptions">Exceptions</a></h2>
<dl class="m-doc">
<dt>exception <a href="content.Class.ClassError.html" class="m-doc">ClassError</a></dt>
<dd>This exception belongs to class</dd>
</dl>
</section>
<section>
<h2>Method documentation</h2>
<section class="m-doc-details" id="class_method"><div>
Expand Down
8 changes: 8 additions & 0 deletions documentation/test_python/content/content.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ <h3>Contents</h3>
<li><a href="#enums">Enums</a></li>
<li><a href="#functions">Functions</a></li>
<li><a href="#data">Data</a></li>
<li><a href="#exceptions">Exceptions</a></li>
</ul>
</li>
</ul>
Expand Down Expand Up @@ -147,6 +148,13 @@ <h2><a href="#data">Data</a></h2>
<dd></dd>
</dl>
</section>
<section id="exceptions">
<h2><a href="#exceptions">Exceptions</a></h2>
<dl class="m-doc">
<dt>exception <a href="content.FreeStandingError.html" class="m-doc">FreeStandingError</a></dt>
<dd>This exception belongs to module</dd>
</dl>
</section>
<section>
<h2>Enum documentation</h2>
<section class="m-doc-details" id="EnumWithSummary"><div>
Expand Down
6 changes: 6 additions & 0 deletions documentation/test_python/content/content/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,12 @@ def property_exception_docs(self):

DATA_WITH_DETAILS: str = 'this blows'

class ClassError(RuntimeError):
"""This exception belongs to class"""

class FreeStandingError(RuntimeError):
"""This exception belongs to module"""

class ClassWithSummary:
"""This class has summary from the docstring"""

Expand Down
2 changes: 1 addition & 1 deletion documentation/test_python/inspect_string/classes.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ <h1>Classes</h2>
<li>class <a href="inspect_string.subpackage.Foo.html" class="m-doc">Foo</a> <span class="m-doc">A class in a subpackage. Shouldn&#x27;t cause the module tree to have an expander for it.</span></li>
</ul>
</li>
<li>class <a href="inspect_string.DerivedException.html" class="m-doc">DerivedException</a> <span class="m-doc">A class deriving from BaseException, which has the weird args getset_descriptor</span></li>
<li>exception <a href="inspect_string.DerivedException.html" class="m-doc">DerivedException</a> <span class="m-doc">A class deriving from BaseException, which has the weird args getset_descriptor</span></li>
<li class="m-doc-collapsible collapsed">
<a href="#" onclick="return toggle(this)">class</a> <a href="inspect_string.Foo.html" class="m-doc">Foo</a> <span class="m-doc">The foo class</span>
<ul class="m-doc">
Expand Down
10 changes: 8 additions & 2 deletions documentation/test_python/inspect_string/inspect_string.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ <h3>Contents</h3>
<li><a href="#enums">Enums</a></li>
<li><a href="#functions">Functions</a></li>
<li><a href="#data">Data</a></li>
<li><a href="#exceptions">Exceptions</a></li>
</ul>
</li>
</ul>
Expand All @@ -62,8 +63,6 @@ <h2><a href="#namespaces">Modules</a></h2>
<section id="classes">
<h2><a href="#classes">Classes</a></h2>
<dl class="m-doc">
<dt>class <a href="inspect_string.DerivedException.html" class="m-doc">DerivedException</a></dt>
<dd>A class deriving from BaseException, which has the weird args getset_descriptor</dd>
<dt>class <a href="inspect_string.Foo.html" class="m-doc">Foo</a></dt>
<dd>The foo class</dd>
<dt>class <a href="inspect_string.FooSlots.html" class="m-doc">FooSlots</a></dt>
Expand Down Expand Up @@ -110,6 +109,13 @@ <h2><a href="#data">Data</a></h2>
<dd></dd>
</dl>
</section>
<section id="exceptions">
<h2><a href="#exceptions">Exceptions</a></h2>
<dl class="m-doc">
<dt>exception <a href="inspect_string.DerivedException.html" class="m-doc">DerivedException</a></dt>
<dd>A class deriving from BaseException, which has the weird args getset_descriptor</dd>
</dl>
</section>
<section>
<h2>Enum documentation</h2>
<section class="m-doc-details" id="MyEnum"><div>
Expand Down