diff --git a/.gitignore b/.gitignore index 1bb85e4..bc74ed0 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,8 @@ __pycache__/ # Distribution / packaging build/ dist/ -*.egg-info/ \ No newline at end of file +*.egg-info/ + +# Sphinx +docs/_build/ +docs/src/api/ diff --git a/INSTALL b/INSTALL index ec3c0df..3be2182 100644 --- a/INSTALL +++ b/INSTALL @@ -2,6 +2,9 @@ python -m pip install . +Development dependencies +python -m pip install -e '.[dev]' + * Uninstallation python -m pip uninstall fvr diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..360b937 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,18 @@ +# Makefile for Sphinx documentation +# sphinx (one of): pip install sphinx, pacman -S python-sphinx + +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = src +BUILDDIR = _build + +# first-target, will also run without arguments (like: make help). +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0) + +.PHONY: help Makefile + +# catch-all target: route all unknown targets to Sphinx. $(0) is shortcut for +# $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0) diff --git a/docs/src/_static/documentation_options.js b/docs/src/_static/documentation_options.js new file mode 100644 index 0000000..4a60816 --- /dev/null +++ b/docs/src/_static/documentation_options.js @@ -0,0 +1,15 @@ +const DOCUMENTATION_OPTIONS = { + VERSION: '', + LANGUAGE: 'en', + COLLAPSE_INDEX: false, + BUILDER: 'html', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: false, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, + // do not collapse entries e.g. in the module index side + DOCUMENTATION_OPTIONS.COLLAPSE_INDEX: false, +}; \ No newline at end of file diff --git a/docs/src/conf.py b/docs/src/conf.py new file mode 100644 index 0000000..394ccf3 --- /dev/null +++ b/docs/src/conf.py @@ -0,0 +1,98 @@ +# Configuration file for the Sphinx documentation builder. +# documentation: https://www.sphinx-doc.org/en/master/usage/configuration.html +# extensions: https://www.sphinx-doc.org/en/master/usage/extensions/ + + +# Project information +project = 'fvr' +author = 'Daniel Weschke' +copyright = '%Y, Daniel Weschke' + + +# General configuration + +extensions = [] # will be appended below + +## Options for internationalisation +language = 'en' + +## Options for source files +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +master_doc = 'index' +source_suffix = '.rst' + +## Options for templating +templates_path = ['_templates'] # relative to conf.py dir + + +# Builder options + +## Options for HTML output +html_theme = 'furo' +html_theme_options = {} +html_static_path = ['_static'] # relative to conf.py dir +html_copy_source = False # copy reST sources to html/sources/ +html_show_sourcelink = False # links to reST sources + + +# Domain options + +## Options for the Python domain +add_module_names = False +modindex_common_prefix = ['fvr.'] # prefix ignored for sorting, used in `Module Index` +# python_display_short_literal_types = True +# python_use_unqualified_type_names = True + + +# built-in extension todo +# add directive `.. todo::` and `.. todolist::` +extensions.append('sphinx.ext.todo') +todo_include_todos = True + + +# built-in extension viewcode +# links to python package module files +extensions.append('sphinx.ext.viewcode') + + +# built-in extension autodoc +extensions.append('sphinx.ext.autodoc') +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 + + +# built-in extension apidoc +extensions.append('sphinx.ext.apidoc') +apidoc_modules = [ + # 'path': relative to conf.py dir + # 'destination': relative to source dir + {'path': '../../src', '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 + + +# built-in extension napoleon +# add docstring styles: Google and NumPy +extensions.append('sphinx.ext.napoleon') +napoleon_google_docstring = True +napoleon_numpy_docstring = True +napoleon_include_init_with_doc = False +napoleon_include_private_with_doc = False +napoleon_include_special_with_doc = True +napoleon_use_admonition_for_examples = False +napoleon_use_admonition_for_notes = False +napoleon_use_admonition_for_references = False +napoleon_use_ivar = False +napoleon_use_param = True +napoleon_use_keyword = True +napoleon_use_rtype = True +napoleon_preprocess_types = False +napoleon_type_aliases = None +napoleon_attr_annotations = True +napoleon_custom_sections = None diff --git a/docs/src/index.rst b/docs/src/index.rst new file mode 100644 index 0000000..939cddd --- /dev/null +++ b/docs/src/index.rst @@ -0,0 +1,24 @@ + +Welcome to fvr's documentation! +=============================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` + +.. + search is in the selected theme visible + * :ref:`search` + + +Todos +----- + +* .. todolist:: diff --git a/pyproject.toml b/pyproject.toml index dbab372..ff315f3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -31,6 +31,24 @@ classifiers = [ dependencies = [ "numpy", ] +[project.optional-dependencies] +docs = ["sphinx", "furo"] +test = ["pytest"] +dev = [ + # recursive optional dependencies + "fvr[docs,test]", + # Useful for building quick scripts, https://github.com/google/python-fire + "fire", + # Code quality tools + "mypy", + # # Improved exception traceback output + # # https://github.com/qix-/better-exceptions + # "better_exceptions", + # # Analyzing dependencies + # # install graphviz to generate graphs + # "graphviz", + # "pipdeptree", +] [tool.setuptools.dynamic] version = {attr = "fvr.__version__"} diff --git a/src/fvr/geom.py b/src/fvr/geom.py index 6551fc4..ae20c38 100644 --- a/src/fvr/geom.py +++ b/src/fvr/geom.py @@ -2,12 +2,13 @@ import re from fvr.typing import FloatArray class polygon: - def __init__(self, vertices: FloatArray|str): - r"""Properties of a simple polygon. + r"""Properties of a simple polygon. - Args: - vertices: List of points, pair of x and y: "[[x1, y1], [x2, y2], ...]" - """ + Args: + vertices: List of points, pair of x and y: "[[x1, y1], [x2, y2], ...]" + """ + + def __init__(self, vertices: FloatArray|str): if isinstance(vertices, str): vertices = self.str2arr(vertices) self.vertices = vertices diff --git a/src/fvr/wire.py b/src/fvr/wire.py index a3d9c2e..351a824 100644 --- a/src/fvr/wire.py +++ b/src/fvr/wire.py @@ -1,14 +1,12 @@ import math class awg: - """AWG wire. + """Parameters of an AWG wire. + + Args: + number: AWG wire size, also '00', '000', '0000' """ def __init__(self, number: int|str): - """Determine parameters for a given AWG wire size. - - Args: - number: AWG wire size, also '00', '000', '0000' - """ self.number = number self._number = self.num2int(number) @@ -27,12 +25,12 @@ class awg: @property def diameter(self): - """The diameter for a given AWG wire size in mm""" + """The diameter of the AWG wire, mm""" return 0.127 * 92**((36-self._number)/39) @property def area(self): - """The area for a given AWG wire size in mm²""" + """The area of the AWG wire, mm²""" return math.pi/4*self.diameter**2 def __str__(self):