diff --git a/docs/src/conf.py b/docs/src/conf.py index 394ccf3..a5fcc5e 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -2,24 +2,34 @@ # documentation: https://www.sphinx-doc.org/en/master/usage/configuration.html # extensions: https://www.sphinx-doc.org/en/master/usage/extensions/ +# INFO: for sidebar api content, the modules.rst must be loaded? hidden? + # Project information project = 'fvr' author = 'Daniel Weschke' copyright = '%Y, Daniel Weschke' +vesion = '25.12.22' +release = '25.12.22' # General configuration - extensions = [] # will be appended below +## Options for highlighting +# pygments_style = None # None: theme default, '' == 'sphinx' +# pygments_dark_style = 'fruity' # '' == 'sphinx' + ## Options for internationalisation language = 'en' +## Options for markup +show_authors = False + ## Options for source files exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] master_doc = 'index' -source_suffix = '.rst' +source_suffix = {'.rst': 'restructuredtext'} ## Options for templating templates_path = ['_templates'] # relative to conf.py dir @@ -29,16 +39,46 @@ templates_path = ['_templates'] # relative to conf.py dir ## Options for HTML output html_theme = 'furo' -html_theme_options = {} +html_theme_options = { + "footer_icons": [ + { + "name": "home", + "url": "/", + "html": """ + + + """, + "class": "", + }, + { + "name": "git", + "url": "https://gitea.weseng.de/daniel/fvr", + "html": """ + + + + """, + "class": "", + }, + ], +} +html_title = f'{project} {release} documentation' html_static_path = ['_static'] # relative to conf.py dir +html_last_updated_fmt = '%b %d, %Y' html_copy_source = False # copy reST sources to html/sources/ html_show_sourcelink = False # links to reST sources +html_file_suffix = '.html' # extension for generated files +html_show_copyright = True # show “© Copyright …” using `copyright' +html_show_search_summary = True +html_show_sphinx = True +html_scaled_image_link = True # Link images that have been resized + # per-image deactivation `:class: no-scaled-link' # Domain options ## Options for the Python domain -add_module_names = False +add_module_names = False # prefix module names to all objects (classes, methods) modindex_common_prefix = ['fvr.'] # prefix ignored for sorting, used in `Module Index` # python_display_short_literal_types = True # python_use_unqualified_type_names = True @@ -57,12 +97,19 @@ extensions.append('sphinx.ext.viewcode') # built-in extension autodoc extensions.append('sphinx.ext.autodoc') +autoclass_content = 'class' # class, init, both (class + init under class) +autodoc_class_signature = 'separated' # mixed (args at class), separated (args at __init__) +autodoc_member_order = 'groupwise' # alphabetical, groupwise, bysource +autodoc_default_options = { + # 'special-members': '__iter__, __contains__, __getitem__, __setitem__, __pos__, __neg__, __add__, __iadd__, __sub__, __isub__, __mul__, __rmul__, __imul__, __matmul__, __imatmul__, __abs__, __lt__, __le__, __gt__, __ge__, __eq__, __ne__, __str__, __repr__' + 'special-members': '__init__, __iter__, __contains__, __getitem__, __setitem__, __pos__, __neg__, __add__, __iadd__, __sub__, __isub__, __mul__, __rmul__, __imul__, __matmul__, __imatmul__, __abs__, __lt__, __le__, __gt__, __ge__, __eq__, __ne__, __str__, __repr__' +} autodoc_typehints = 'description' # show typehints in 'signature', 'description', 'both', 'none' # autodoc_type_alias = { # 'Callable': 'Callable', # otherwise Callable -> collections.abc.Callable # 'ArrayLike': 'ArrayLike', # otherwise ArrayLike -> _SupportsArray[dtype[Any]] | ... # } -autodoc_typehints_format = 'short' # 'short': e.g. io.StringIO -> StringIO +autodoc_typehints_format = 'short' # 'short': e.g. io.StringIO -> StringIO # built-in extension apidoc @@ -70,11 +117,15 @@ extensions.append('sphinx.ext.apidoc') apidoc_modules = [ # 'path': relative to conf.py dir # 'destination': relative to source dir - {'path': '../../src', 'destination': './api'} + {'path': '../../src/fvr', 'destination': './api'} ] apidoc_max_depth = 4 apidoc_separate_modules = True # doc for each module on an individual page apidoc_module_first = True # module doc before submodule doc +apidoc_implicit_namespaces = True # True: any folder is a packages, even w/o __init.py +apidoc_automodule_options = { + 'members', 'show-inheritance', 'undoc-members' +} # built-in extension napoleon diff --git a/docs/src/index.rst b/docs/src/index.rst index 939cddd..8c18a70 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -3,8 +3,10 @@ Welcome to fvr's documentation! =============================== .. toctree:: - :maxdepth: 2 - :caption: Contents: + :maxdepth: 4 + :titlesonly: + + api/fvr Indices and tables diff --git a/pyproject.toml b/pyproject.toml index ff315f3..65ac971 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -31,6 +31,7 @@ classifiers = [ dependencies = [ "numpy", ] + [project.optional-dependencies] docs = ["sphinx", "furo"] test = ["pytest"] diff --git a/src/fvr/geom.py b/src/fvr/geom.py index ae20c38..e635181 100644 --- a/src/fvr/geom.py +++ b/src/fvr/geom.py @@ -3,12 +3,13 @@ from fvr.typing import FloatArray class polygon: r"""Properties of a simple polygon. - - Args: - vertices: List of points, pair of x and y: "[[x1, y1], [x2, y2], ...]" """ def __init__(self, vertices: FloatArray|str): + r""" + Args: + vertices: List of points, pair of x and y: ``[[x1, y1], [x2, y2], ...]`` + """ if isinstance(vertices, str): vertices = self.str2arr(vertices) self.vertices = vertices diff --git a/src/fvr/wire.py b/src/fvr/wire.py index 351a824..a4c2dbe 100644 --- a/src/fvr/wire.py +++ b/src/fvr/wire.py @@ -2,11 +2,12 @@ import math class awg: """Parameters of an AWG wire. - - Args: - number: AWG wire size, also '00', '000', '0000' """ def __init__(self, number: int|str): + """ + Args: + number: AWG wire size, also '00', '000', '0000' + """ self.number = number self._number = self.num2int(number)