content module
This overwrites the docstring for content.
This is detailed module docs. I kinda hate how it needs to be indented, tho. Below is an included file to test file path is supplied somewhat correctly (relative to the input dir):
# This module has an external summary
Modules
- module docstring_summary
- This module retains summary from the docstring
- module submodule
- This submodule has an external summary.
Classes
- class Class
- This overwrites the docstring for Class.
- class ClassDocumentingItsMembers
- This class documents its members directly in its own directive
- class ClassWithSlots
- This class has slots and those have to be documented externally
- class ClassWithSummary
- This class has summary from the docstring
Enums
Functions
- def exception_docs()
- This one documents raised exceptions in an (otherwise unneeded) detail view
- def foo(a, b)
- This overwrites the docstring for foo(), but doesn't add any detailed block.
- def foo_with_details(a, b)
- This overwrites the docstring for foo_with_details().
- def full_docstring(a, b) -> str
- This function has a full docstring.
- def function_with_summary()
- This function has summary from the docstring
- def param_docs(a: int, b, c: float) -> str
- Detailed param docs and annotations
- def param_docs_wrong(a, b)
- Should give warnings
- def this_function_has_bad_docs(a, b)
Data
- ANOTHER_DOCUMENTED_INSIDE_MODULE = 3
- In-module summary for another data
- CONSTANT: float = 3.14
- This is finally a docstring for CONSTANT
- DATA_DOCUMENTED_INSIDE_MODULE: float = 6.28
- In-module summary for the data member
- DATA_WITH_DETAILS: str = 'heyoo'
- This is finally a docstring for DATA_WITH_DETAILS
- DATA_WITH_DETAILS_BUT_NO_SUMMARY_NEITHER_TYPE = None
Enum documentation
class content. EnumWithSummary(enum.Enum)
This summary is preserved
Enumerators | |
---|---|
VALUE |
Value docs where this is treated as summary. And this as detailed docs by the raw docstring parser, but the theme doesn't distinguish between them so they get merged together. |
ANOTHER |
This value is documented from within the |
THIRD |
... while this comes from the |
And this is detailed docs added to the docstring summary. VALUE!!
Function documentation
def content. exception_docs()
This one documents raised exceptions in an (otherwise unneeded) detail view
Exceptions | |
---|---|
ValueError | This thing fires |
ValueError | This same thing fires also for this reason |
RuntimeError | This another thing fires too |
def content. foo_with_details(a, b)
This overwrites the docstring for foo_with_details().
def content. full_docstring(a, b) -> str
This function has a full docstring.
Parameters | |
---|---|
a | First parameter |
b | Second |
It takes one parameter and also another, which are documented externally, but not overwriting the in-source docstring. The details are in two paragraphs, each wrapped in its own `<p>`, but not additionally formatted or parsed in any way.
Like this.
def content. function_with_summary()
This function has summary from the docstring
This function has external details but summary from the docstring.
def content. param_docs(a: int,
b,
c: float) -> str
Detailed param docs and annotations
Parameters | |
---|---|
a | First parameter |
b | The second one is different from a |
c | And a float |
Returns | String, of course, it's all stringly typed |
Type annotations and param list in detailed docs.
def content. param_docs_wrong(a, b)
Should give warnings
Parameters | |
---|---|
a | First |
b |
The b
is not documented, while c
isn't in the signature.
def content. this_function_has_bad_docs(a, b)
Parameters | |
---|---|
a | |
b |
Data documentation
content. DATA_WITH_DETAILS: str
This is finally a docstring for DATA_WITH_DETAILS
Detailed docs for the data. YAY.
content. DATA_WITH_DETAILS_BUT_NO_SUMMARY_NEITHER_TYPE
Why it has to be yelling?!