add docs

.gitignore

@@ -6,3 +6,7 @@ __pycache__/
 build/
 dist/
 *.egg-info/
+
+# Sphinx
+docs/_build/
+docs/src/api/

INSTALL

@@ -2,6 +2,9 @@
 
 python -m pip install .
 
+Development dependencies
+python -m pip install -e '.[dev]'
+
 * Uninstallation
 
 python -m pip uninstall fvr

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)

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,
+};

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

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::

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__"}

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

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):