WIP Markdown support
parent
1715dfe0b5
commit
4568f5a0d4
@ -0,0 +1,7 @@
|
|||||||
|
{{ md_fence + "{" + obj.type + "}" }} {{ obj.name }}
|
||||||
|
{% if summary %}
|
||||||
|
|
||||||
|
{{ obj.summary }}
|
||||||
|
|
||||||
|
{% endif %}
|
||||||
|
{{ md_fence }}
|
@ -0,0 +1,15 @@
|
|||||||
|
# API Reference
|
||||||
|
|
||||||
|
This page contains auto-generated API reference documentation [^f1].
|
||||||
|
|
||||||
|
{{ md_fence }}{toctree}
|
||||||
|
:titlesonly:
|
||||||
|
|
||||||
|
{% for page in pages %}
|
||||||
|
{% if page.top_level_object and page.display %}
|
||||||
|
{{ page.include_path }}
|
||||||
|
{% endif %}
|
||||||
|
{% endfor %}
|
||||||
|
{{ md_fence }}
|
||||||
|
|
||||||
|
[^f1]: Created with [sphinx-autoapi](https://github.com/readthedocs/sphinx-autoapi)
|
@ -0,0 +1 @@
|
|||||||
|
{% extends "python/data.md" %}
|
@ -0,0 +1,60 @@
|
|||||||
|
{% if obj.display %}
|
||||||
|
{{ md_fence + "{py:" + obj.type + "} " + obj.short_name }}{% if obj.args %}({{ obj.args }}){% endif %}
|
||||||
|
{% for (args, return_annotation) in obj.overloads %}
|
||||||
|
{{ " " * (obj.type | length) }} {{ obj.short_name }}{% if args %}({{ args }}){% endif %}
|
||||||
|
{% endfor %}
|
||||||
|
|
||||||
|
|
||||||
|
{% if obj.bases %}
|
||||||
|
{% if "show-inheritance" in autoapi_options %}
|
||||||
|
Bases: {% for base in obj.bases %}{{ base|link_objs }}{% if not loop.last %}, {% endif %}{% endfor %}
|
||||||
|
{% endif %}
|
||||||
|
|
||||||
|
|
||||||
|
{% if "show-inheritance-diagram" in autoapi_options and obj.bases != ["object"] %}
|
||||||
|
{{ md_fence + "{autoapi-inheritance-diagram} " + obj.obj["full_name"] }}
|
||||||
|
:parts: 1
|
||||||
|
{% if "private-members" in autoapi_options %}
|
||||||
|
:private-bases:
|
||||||
|
{% endif %}
|
||||||
|
{{ md_fence }}
|
||||||
|
|
||||||
|
{% endif %}
|
||||||
|
{% endif %}
|
||||||
|
{% if obj.docstring %}
|
||||||
|
{{ obj.docstring|indent(3) }}
|
||||||
|
{% endif %}
|
||||||
|
{% if "inherited-members" in autoapi_options %}
|
||||||
|
{% set visible_classes = obj.classes|selectattr("display")|list %}
|
||||||
|
{% else %}
|
||||||
|
{% set visible_classes = obj.classes|rejectattr("inherited")|selectattr("display")|list %}
|
||||||
|
{% endif %}
|
||||||
|
{% for klass in visible_classes %}
|
||||||
|
{{ klass.render()|indent(3) }}
|
||||||
|
{% endfor %}
|
||||||
|
{% if "inherited-members" in autoapi_options %}
|
||||||
|
{% set visible_properties = obj.properties|selectattr("display")|list %}
|
||||||
|
{% else %}
|
||||||
|
{% set visible_properties = obj.properties|rejectattr("inherited")|selectattr("display")|list %}
|
||||||
|
{% endif %}
|
||||||
|
{% for property in visible_properties %}
|
||||||
|
{{ property.render()|indent(3) }}
|
||||||
|
{% endfor %}
|
||||||
|
{% if "inherited-members" in autoapi_options %}
|
||||||
|
{% set visible_attributes = obj.attributes|selectattr("display")|list %}
|
||||||
|
{% else %}
|
||||||
|
{% set visible_attributes = obj.attributes|rejectattr("inherited")|selectattr("display")|list %}
|
||||||
|
{% endif %}
|
||||||
|
{% for attribute in visible_attributes %}
|
||||||
|
{{ attribute.render()|indent(3) }}
|
||||||
|
{% endfor %}
|
||||||
|
{% if "inherited-members" in autoapi_options %}
|
||||||
|
{% set visible_methods = obj.methods|selectattr("display")|list %}
|
||||||
|
{% else %}
|
||||||
|
{% set visible_methods = obj.methods|rejectattr("inherited")|selectattr("display")|list %}
|
||||||
|
{% endif %}
|
||||||
|
{% for method in visible_methods %}
|
||||||
|
{{ method.render()|indent(3) }}
|
||||||
|
{% endfor %}
|
||||||
|
{{ md_fence }}
|
||||||
|
{% endif %}
|
@ -0,0 +1,35 @@
|
|||||||
|
{% if obj.display %}
|
||||||
|
{{ md_fence + "{py:" + obj.type + "} " + obj.name }}
|
||||||
|
{%- if obj.annotation is not none %}
|
||||||
|
|
||||||
|
:type: {%- if obj.annotation %} {{ obj.annotation }}{%- endif %}
|
||||||
|
|
||||||
|
{%- endif %}
|
||||||
|
|
||||||
|
{%- if obj.value is not none %}
|
||||||
|
|
||||||
|
:value: {% if obj.value is string and obj.value.splitlines()|count > 1 -%}
|
||||||
|
Multiline-String
|
||||||
|
|
||||||
|
{{ md_fence }}{raw} html
|
||||||
|
|
||||||
|
<details><summary>Show Value</summary>
|
||||||
|
{{ md_fence }}
|
||||||
|
|
||||||
|
```python
|
||||||
|
"""{{ obj.value|indent(width=8,blank=true) }}"""
|
||||||
|
```
|
||||||
|
|
||||||
|
{{ md_fence }}{raw} html
|
||||||
|
|
||||||
|
</details>
|
||||||
|
{{ md_fence }}
|
||||||
|
{%- else -%}
|
||||||
|
{{ "%r" % obj.value|string|truncate(100) }}
|
||||||
|
{%- endif %}
|
||||||
|
{%- endif %}
|
||||||
|
|
||||||
|
|
||||||
|
{{ obj.docstring|indent(3) }}
|
||||||
|
{{ md_fence }}
|
||||||
|
{% endif %}
|
@ -0,0 +1 @@
|
|||||||
|
{% extends "python/class.md" %}
|
@ -0,0 +1,16 @@
|
|||||||
|
{% if obj.display %}
|
||||||
|
{{ md_fence + "{py:function} " + obj.short_name + "(" + obj.args + ")" }}{% if obj.return_annotation is not none %} -> {{ obj.return_annotation }}{% endif %}
|
||||||
|
|
||||||
|
{% for (args, return_annotation) in obj.overloads %}
|
||||||
|
{{ obj.short_name }}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %}
|
||||||
|
|
||||||
|
{% endfor %}
|
||||||
|
{% for property in obj.properties %}
|
||||||
|
:{{ property }}:
|
||||||
|
{% endfor %}
|
||||||
|
|
||||||
|
{% if obj.docstring %}
|
||||||
|
{{ obj.docstring|indent(3) }}
|
||||||
|
{% endif %}
|
||||||
|
{% endif %}
|
||||||
|
{{ md_fence }}
|
@ -0,0 +1,20 @@
|
|||||||
|
{%- if obj.display %}
|
||||||
|
{{ md_fence + "{py:method} " + obj.short_name + "(" + obj.args + ")" }}{% if obj.return_annotation is not none %} -> {{ obj.return_annotation }}{% endif %}
|
||||||
|
|
||||||
|
{% for (args, return_annotation) in obj.overloads %}
|
||||||
|
{{ obj.short_name }}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %}
|
||||||
|
|
||||||
|
{% endfor %}
|
||||||
|
{% if obj.properties %}
|
||||||
|
{% for property in obj.properties %}
|
||||||
|
:{{ property }}:
|
||||||
|
{% endfor %}
|
||||||
|
|
||||||
|
{% else %}
|
||||||
|
|
||||||
|
{% endif %}
|
||||||
|
{% if obj.docstring %}
|
||||||
|
{{ obj.docstring|indent(3) }}
|
||||||
|
{% endif %}
|
||||||
|
{% endif %}
|
||||||
|
{{ md_fence }}
|
@ -0,0 +1,113 @@
|
|||||||
|
{% if not obj.display %}
|
||||||
|
:orphan:
|
||||||
|
|
||||||
|
{% endif %}
|
||||||
|
# {py:mod}`{{ obj.name }}`
|
||||||
|
|
||||||
|
{{ md_fence + "{py:module} " + obj.name }}
|
||||||
|
{{ md_fence }}
|
||||||
|
|
||||||
|
{% if obj.docstring %}
|
||||||
|
{{ md_fence }}{autoapi-nested-parse}
|
||||||
|
|
||||||
|
{{ obj.docstring|indent(3) }}
|
||||||
|
{{ md_fence}}
|
||||||
|
|
||||||
|
{% endif %}
|
||||||
|
|
||||||
|
{% block subpackages %}
|
||||||
|
{% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
|
||||||
|
{% if visible_subpackages %}
|
||||||
|
## Subpackages
|
||||||
|
{{ md_fence }}{toctree}
|
||||||
|
:titlesonly:
|
||||||
|
:maxdepth: 3
|
||||||
|
|
||||||
|
{% for subpackage in visible_subpackages %}
|
||||||
|
{{ subpackage.short_name }}/index.rst
|
||||||
|
{% endfor %}
|
||||||
|
{{ md_fence }}
|
||||||
|
|
||||||
|
{% endif %}
|
||||||
|
{% endblock %}
|
||||||
|
{% block submodules %}
|
||||||
|
{% set visible_submodules = obj.submodules|selectattr("display")|list %}
|
||||||
|
{% if visible_submodules %}
|
||||||
|
## Submodules
|
||||||
|
{{ md_fence }}{toctree}
|
||||||
|
:titlesonly:
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
{% for submodule in visible_submodules %}
|
||||||
|
{{ submodule.short_name }}/index.rst
|
||||||
|
{% endfor %}
|
||||||
|
{{ md_fence }}
|
||||||
|
|
||||||
|
|
||||||
|
{% endif %}
|
||||||
|
{% endblock %}
|
||||||
|
{% block content %}
|
||||||
|
{% if obj.all is not none %}
|
||||||
|
{% set visible_children = obj.children|selectattr("short_name", "in", obj.all)|list %}
|
||||||
|
{% elif obj.type is equalto("package") %}
|
||||||
|
{% set visible_children = obj.children|selectattr("display")|list %}
|
||||||
|
{% else %}
|
||||||
|
{% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %}
|
||||||
|
{% endif %}
|
||||||
|
{% if visible_children %}
|
||||||
|
## {{ obj.type|title }} Contents
|
||||||
|
|
||||||
|
{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %}
|
||||||
|
{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %}
|
||||||
|
{% set visible_attributes = visible_children|selectattr("type", "equalto", "data")|list %}
|
||||||
|
{% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %}
|
||||||
|
{% block classes scoped %}
|
||||||
|
{% if visible_classes %}
|
||||||
|
### Classes
|
||||||
|
|
||||||
|
{{ md_fence }}{autoapisummary}
|
||||||
|
|
||||||
|
{% for klass in visible_classes %}
|
||||||
|
{{ klass.id }}
|
||||||
|
{% endfor %}
|
||||||
|
{{ md_fence }}
|
||||||
|
|
||||||
|
|
||||||
|
{% endif %}
|
||||||
|
{% endblock %}
|
||||||
|
|
||||||
|
{% block functions scoped %}
|
||||||
|
{% if visible_functions %}
|
||||||
|
### Functions
|
||||||
|
|
||||||
|
{{ md_fence }}{autoapisummary}
|
||||||
|
|
||||||
|
{% for function in visible_functions %}
|
||||||
|
{{ function.id }}
|
||||||
|
{% endfor %}
|
||||||
|
{{ md_fence }}
|
||||||
|
|
||||||
|
|
||||||
|
{% endif %}
|
||||||
|
{% endblock %}
|
||||||
|
|
||||||
|
{% block attributes scoped %}
|
||||||
|
{% if visible_attributes %}
|
||||||
|
### Attributes
|
||||||
|
|
||||||
|
{{ md_fence }}{autoapisummary}
|
||||||
|
|
||||||
|
{% for attribute in visible_attributes %}
|
||||||
|
{{ attribute.id }}
|
||||||
|
{% endfor %}
|
||||||
|
{{ md_fence }}
|
||||||
|
|
||||||
|
|
||||||
|
{% endif %}
|
||||||
|
{% endblock %}
|
||||||
|
{% endif %}
|
||||||
|
{% for obj_item in visible_children %}
|
||||||
|
{{ obj_item.render()|indent(0) }}
|
||||||
|
{% endfor %}
|
||||||
|
{% endif %}
|
||||||
|
{% endblock %}
|
@ -0,0 +1 @@
|
|||||||
|
{% extends "python/module.md" %}
|
@ -0,0 +1,16 @@
|
|||||||
|
{%- if obj.display %}
|
||||||
|
{{ md_fence }}{py:property} {{ obj.short_name }}
|
||||||
|
{% if obj.annotation %}
|
||||||
|
:type: {{ obj.annotation }}
|
||||||
|
{% endif %}
|
||||||
|
{% if obj.properties %}
|
||||||
|
{% for property in obj.properties %}
|
||||||
|
:{{ property }}:
|
||||||
|
{% endfor %}
|
||||||
|
{% endif %}
|
||||||
|
|
||||||
|
{% if obj.docstring %}
|
||||||
|
{{ obj.docstring|indent(3) }}
|
||||||
|
{% endif %}
|
||||||
|
{{ md_fence }}
|
||||||
|
{% endif %}
|
@ -0,0 +1,240 @@
|
|||||||
|
# {py:mod}`example`
|
||||||
|
|
||||||
|
:::{py:module} example
|
||||||
|
:::
|
||||||
|
|
||||||
|
:::{autoapi-nested-parse}
|
||||||
|
|
||||||
|
Example module
|
||||||
|
|
||||||
|
This is a description
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
|
||||||
|
## Module Contents
|
||||||
|
|
||||||
|
### Classes
|
||||||
|
|
||||||
|
:::{autoapisummary}
|
||||||
|
|
||||||
|
example.Foo
|
||||||
|
example.Bar
|
||||||
|
example.ClassWithNoInit
|
||||||
|
example.One
|
||||||
|
example.MultilineOne
|
||||||
|
example.Two
|
||||||
|
:::
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### Functions
|
||||||
|
|
||||||
|
:::{autoapisummary}
|
||||||
|
|
||||||
|
example.decorator_okay
|
||||||
|
example.fn_with_long_sig
|
||||||
|
:::
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### Attributes
|
||||||
|
|
||||||
|
:::{autoapisummary}
|
||||||
|
|
||||||
|
example.A_TUPLE
|
||||||
|
example.A_LIST
|
||||||
|
:::
|
||||||
|
|
||||||
|
|
||||||
|
:::{py:data} A_TUPLE
|
||||||
|
:value: "('a', 'b')"
|
||||||
|
|
||||||
|
A tuple to be rendered as a tuple.
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
:::{py:data} A_LIST
|
||||||
|
:value: "['c', 'd']"
|
||||||
|
|
||||||
|
A list to be rendered as a list.
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
:::{py:class} Foo(attr)
|
||||||
|
|
||||||
|
Bases: :py:obj:`object`
|
||||||
|
|
||||||
|
Can we parse arguments from the class docstring?
|
||||||
|
|
||||||
|
:param attr: Set an attribute.
|
||||||
|
:type attr: str
|
||||||
|
|
||||||
|
Constructor docstring
|
||||||
|
|
||||||
|
:::{py:class} Meta
|
||||||
|
|
||||||
|
Bases: :py:obj:`object`
|
||||||
|
|
||||||
|
A nested class just to test things out
|
||||||
|
|
||||||
|
:::{py:method} foo()
|
||||||
|
:classmethod:
|
||||||
|
|
||||||
|
The foo class method
|
||||||
|
|
||||||
|
:::
|
||||||
|
:::
|
||||||
|
|
||||||
|
:::{py:property} property_simple
|
||||||
|
:type: int
|
||||||
|
|
||||||
|
This property should parse okay.
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
:::{py:attribute} class_var
|
||||||
|
:value: '42'
|
||||||
|
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
:::{py:attribute} another_class_var
|
||||||
|
:value: '42'
|
||||||
|
|
||||||
|
Another class var docstring
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
:::{py:attribute} attr2
|
||||||
|
|
||||||
|
This is the docstring of an instance attribute.
|
||||||
|
|
||||||
|
:type: str
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
:::{py:method} method_okay(foo=None, bar=None)
|
||||||
|
|
||||||
|
This method should parse okay
|
||||||
|
|
||||||
|
:::
|
||||||
|
:::{py:method} method_multiline(foo=None, bar=None, baz=None)
|
||||||
|
|
||||||
|
This is on multiple lines, but should parse okay too
|
||||||
|
|
||||||
|
pydocstyle gives us lines of source. Test if this means that multiline
|
||||||
|
definitions are covered in the way we're anticipating here
|
||||||
|
|
||||||
|
:::
|
||||||
|
:::{py:method} method_tricky(foo=None, bar=dict(foo=1, bar=2))
|
||||||
|
|
||||||
|
This will likely fail our argument testing
|
||||||
|
|
||||||
|
We parse naively on commas, so the nested dictionary will throw this off
|
||||||
|
|
||||||
|
:::
|
||||||
|
:::{py:method} method_sphinx_docs(foo, bar=0)
|
||||||
|
|
||||||
|
This method is documented with sphinx style docstrings.
|
||||||
|
|
||||||
|
:param foo: The first argument.
|
||||||
|
:type foo: int
|
||||||
|
|
||||||
|
:param int bar: The second argument.
|
||||||
|
|
||||||
|
:returns: The sum of foo and bar.
|
||||||
|
:rtype: int
|
||||||
|
|
||||||
|
:::
|
||||||
|
:::{py:method} method_google_docs(foo, bar=0)
|
||||||
|
|
||||||
|
This method is documented with google style docstrings.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
foo (int): The first argument.
|
||||||
|
bar (int): The second argument.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
int: The sum of foo and bar.
|
||||||
|
|
||||||
|
:::
|
||||||
|
:::{py:method} method_sphinx_unicode()
|
||||||
|
|
||||||
|
This docstring uses unicodé.
|
||||||
|
|
||||||
|
:returns: A string.
|
||||||
|
:rtype: str
|
||||||
|
|
||||||
|
:::
|
||||||
|
:::{py:method} method_google_unicode()
|
||||||
|
|
||||||
|
This docstring uses unicodé.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
str: A string.
|
||||||
|
|
||||||
|
:::
|
||||||
|
:::
|
||||||
|
|
||||||
|
:::{py:function} decorator_okay(func)
|
||||||
|
|
||||||
|
This decorator should parse okay.
|
||||||
|
|
||||||
|
:::
|
||||||
|
:::{py:class} Bar(attr)
|
||||||
|
|
||||||
|
Bases: :py:obj:`Foo`
|
||||||
|
|
||||||
|
Can we parse arguments from the class docstring?
|
||||||
|
|
||||||
|
:param attr: Set an attribute.
|
||||||
|
:type attr: str
|
||||||
|
|
||||||
|
Constructor docstring
|
||||||
|
|
||||||
|
:::{py:method} method_okay(foo=None, bar=None)
|
||||||
|
|
||||||
|
This method should parse okay
|
||||||
|
|
||||||
|
:::
|
||||||
|
:::
|
||||||
|
|
||||||
|
:::{py:class} ClassWithNoInit
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
:::{py:class} One
|
||||||
|
|
||||||
|
One.
|
||||||
|
|
||||||
|
One __init__.
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
:::{py:class} MultilineOne
|
||||||
|
|
||||||
|
Bases: :py:obj:`One`
|
||||||
|
|
||||||
|
This is a naughty summary line
|
||||||
|
that exists on two lines.
|
||||||
|
|
||||||
|
One __init__.
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
:::{py:class} Two
|
||||||
|
|
||||||
|
Bases: :py:obj:`One`
|
||||||
|
|
||||||
|
Two.
|
||||||
|
|
||||||
|
One __init__.
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
:::{py:function} fn_with_long_sig(this, *, function=None, has=True, quite=True, a, long, signature, many, keyword, arguments)
|
||||||
|
|
||||||
|
A function with a long signature.
|
||||||
|
|
||||||
|
:::
|
@ -0,0 +1,11 @@
|
|||||||
|
# API Reference
|
||||||
|
|
||||||
|
This page contains auto-generated API reference documentation [^f1].
|
||||||
|
|
||||||
|
:::{toctree}
|
||||||
|
:titlesonly:
|
||||||
|
|
||||||
|
/autoapi/example/index
|
||||||
|
:::
|
||||||
|
|
||||||
|
[^f1]: Created with [sphinx-autoapi](https://github.com/readthedocs/sphinx-autoapi)
|
@ -0,0 +1,23 @@
|
|||||||
|
# -*- coding: utf-8 -*-
|
||||||
|
|
||||||
|
templates_path = ["_templates"]
|
||||||
|
source_suffix = {".md": "markdown"}
|
||||||
|
master_doc = "index"
|
||||||
|
project = "pymarkdownexample"
|
||||||
|
copyright = "2015, readthedocs"
|
||||||
|
author = "readthedocs"
|
||||||
|
version = "0.1"
|
||||||
|
release = "0.1"
|
||||||
|
language = "en"
|
||||||
|
exclude_patterns = ["_build"]
|
||||||
|
pygments_style = "sphinx"
|
||||||
|
todo_include_todos = False
|
||||||
|
html_theme = "alabaster"
|
||||||
|
htmlhelp_basename = "pymarkdownexampledoc"
|
||||||
|
extensions = ["myst_parser", "sphinx.ext.autodoc", "autoapi.extension"]
|
||||||
|
myst_enable_extensions = ["colon_fence", "fieldlist"]
|
||||||
|
autoapi_type = "python"
|
||||||
|
autoapi_dirs = ["example"]
|
||||||
|
autoapi_file_pattern = "*.py"
|
||||||
|
autoapi_python_class_content = "both"
|
||||||
|
autoapi_keep_files = True
|
@ -0,0 +1,159 @@
|
|||||||
|
# -*- coding: utf-8 -*-
|
||||||
|
"""Example module
|
||||||
|
|
||||||
|
This is a description
|
||||||
|
"""
|
||||||
|
|
||||||
|
A_TUPLE = ("a", "b")
|
||||||
|
"""A tuple to be rendered as a tuple."""
|
||||||
|
A_LIST = ["c", "d"]
|
||||||
|
"""A list to be rendered as a list."""
|
||||||
|
|
||||||
|
|
||||||
|
class Foo(object):
|
||||||
|
"""Can we parse arguments from the class docstring?
|
||||||
|
|
||||||
|
:param attr: Set an attribute.
|
||||||
|
:type attr: str
|
||||||
|
"""
|
||||||
|
|
||||||
|
class_var = 42 #: Class var docstring
|
||||||
|
|
||||||
|
another_class_var = 42
|
||||||
|
"""Another class var docstring"""
|
||||||
|
|
||||||
|
class Meta(object):
|
||||||
|
"""A nested class just to test things out"""
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def foo():
|
||||||
|
"""The foo class method"""
|
||||||
|
return True
|
||||||
|
|
||||||
|
def __init__(self, attr):
|
||||||
|
"""Constructor docstring"""
|
||||||
|
self.attr = attr
|
||||||
|
self.attr2 = attr
|
||||||
|
"""This is the docstring of an instance attribute.
|
||||||
|
|
||||||
|
:type: str
|
||||||
|
"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
def property_simple(self) -> int:
|
||||||
|
"""This property should parse okay."""
|
||||||
|
return 42
|
||||||
|
|
||||||
|
def method_okay(self, foo=None, bar=None):
|
||||||
|
"""This method should parse okay"""
|
||||||
|
return True
|
||||||
|
|
||||||
|
def method_multiline(self, foo=None, bar=None, baz=None):
|
||||||
|
"""This is on multiple lines, but should parse okay too
|
||||||
|
|
||||||
|
pydocstyle gives us lines of source. Test if this means that multiline
|
||||||
|
definitions are covered in the way we're anticipating here
|
||||||
|
"""
|
||||||
|
return True
|
||||||
|
|
||||||
|
def method_tricky(self, foo=None, bar=dict(foo=1, bar=2)):
|
||||||
|
"""This will likely fail our argument testing
|
||||||
|
|
||||||
|
We parse naively on commas, so the nested dictionary will throw this off
|
||||||
|
"""
|
||||||
|
return True
|
||||||
|
|
||||||
|
def method_sphinx_docs(self, foo, bar=0):
|
||||||
|
"""This method is documented with sphinx style docstrings.
|
||||||
|
|
||||||
|
:param foo: The first argument.
|
||||||
|
:type foo: int
|
||||||
|
|
||||||
|
:param int bar: The second argument.
|
||||||
|
|
||||||
|
:returns: The sum of foo and bar.
|
||||||
|
:rtype: int
|
||||||
|
"""
|
||||||
|
return foo + bar
|
||||||
|
|
||||||
|
def method_google_docs(self, foo, bar=0):
|
||||||
|
"""This method is documented with google style docstrings.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
foo (int): The first argument.
|
||||||
|
bar (int): The second argument.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
int: The sum of foo and bar.
|
||||||
|
"""
|
||||||
|
return foo + bar
|
||||||
|
|
||||||
|
def method_sphinx_unicode(self):
|
||||||
|
"""This docstring uses unicodé.
|
||||||
|
|
||||||
|
:returns: A string.
|
||||||
|
:rtype: str
|
||||||
|
"""
|
||||||
|
return "sphinx"
|
||||||
|
|
||||||
|
def method_google_unicode(self):
|
||||||
|
"""This docstring uses unicodé.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
str: A string.
|
||||||
|
"""
|
||||||
|
return "google"
|
||||||
|
|
||||||
|
|
||||||
|
Foo.bar = "dinglebop"
|
||||||
|
|
||||||
|
|
||||||
|
def decorator_okay(func):
|
||||||
|
"""This decorator should parse okay."""
|
||||||
|
|
||||||
|
def wrapper(*args, **kwargs):
|
||||||
|
return func(*args, **kwargs)
|
||||||
|
|
||||||
|
return wrapper
|
||||||
|
|
||||||
|
|
||||||
|
class Bar(Foo):
|
||||||
|
def method_okay(self, foo=None, bar=None):
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
class ClassWithNoInit:
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
class One:
|
||||||
|
"""One."""
|
||||||
|
|
||||||
|
def __init__(self):
|
||||||
|
"""One __init__."""
|
||||||
|
super().__init__()
|
||||||
|
|
||||||
|
|
||||||
|
class MultilineOne(One):
|
||||||
|
"""This is a naughty summary line
|
||||||
|
that exists on two lines."""
|
||||||
|
|
||||||
|
|
||||||
|
class Two(One):
|
||||||
|
"""Two."""
|
||||||
|
|
||||||
|
|
||||||
|
def fn_with_long_sig(
|
||||||
|
this,
|
||||||
|
*,
|
||||||
|
function=None,
|
||||||
|
has=True,
|
||||||
|
quite=True,
|
||||||
|
a,
|
||||||
|
long,
|
||||||
|
signature,
|
||||||
|
many,
|
||||||
|
keyword,
|
||||||
|
arguments
|
||||||
|
):
|
||||||
|
"""A function with a long signature."""
|
@ -0,0 +1,13 @@
|
|||||||
|
# Welcome to pymarkdownexample's documentation!
|
||||||
|
|
||||||
|
:::{toctree}
|
||||||
|
manualapi
|
||||||
|
:::
|
||||||
|
|
||||||
|
|
||||||
|
Indices and tables
|
||||||
|
==================
|
||||||
|
|
||||||
|
* :ref:`genindex`
|
||||||
|
* :ref:`modindex`
|
||||||
|
* :ref:`search`
|
@ -0,0 +1,11 @@
|
|||||||
|
# Autodoc Directives
|
||||||
|
|
||||||
|
:::{autoapimodule} example
|
||||||
|
:members:
|
||||||
|
:noindex:
|
||||||
|
:::
|
||||||
|
|
||||||
|
|
||||||
|
:::{autoapidecorator} example.decorator_okay
|
||||||
|
:noindex:
|
||||||
|
:::
|
Loading…
Reference in New Issue