Doc update: installation instruction and API reference

README.md

@@ -30,37 +30,23 @@ _vsketch_ is the sum of two things:
 You can help by providing feedback and improving the documentation.*
 
 
-## Installing and Running the examples
+## Installing *vsketch*
 
-**Note**: A Python interpreter must be installed to use *vsketch*. Python 3.9 is recommanded. Python 3.7 and 3.8 are also compatible but *vsketch* is not yet compatible with Python 3.10. See *vpype*'s [installation instructions](https://vpype.readthedocs.io/en/latest/install.html) for more information and platform-specific details.
-
-The easiest way to get started is to obtain a local copy of *vsketch*'s repository and run the examples. 
-
-```bash
-$ git clone https://github.com/abey79/vsketch
-$ cd vsketch
-```
-
-Create a virtual environment and activate it:
+The recommended way to install *vsketch* is as a stand-alone installation using pipx:
 
 ```bash
-$ python3 -m venv venv
-$ source venv/bin/activate
+$ pipx install git+https://github.com/abey79/vsketch
 ```
 
-Install *vsketch*:
+To run the examples, they must be [downloaded](https://github.com/abey79/vsketch/archive/refs/heads/master.zip) separately. After uncompressing the archive, they can be run using the following command:
 
 ```bash
-$ pip install .
+$ vsk run path/to/vsketch-master/examples/shotter
 ```
 
-You are read to run the examples:
-
-```bash
-$ vsk run examples/quick_draw
-```
+Check the [installation instructions](https://vsketch.readthedocs.io/en/latest/install.html) for more details.
 
-Additional examples may be found in the author's [personal collection of sketches](https://github.com/abey79/sketches).
+**Note**: installing *vsketch* on Apple-silicon Macs requires special steps. Please check the [installation instructions](https://vsketch.readthedocs.io/en/latest/install.html) for more information.
 
 
 ## Getting started

docs/.gitignore

@@ -1,2 +1,2 @@
 /_build
-/reference/
+/autoapi

docs/_static/css/label.css

@@ -0,0 +1,16 @@
+.summarylabel {
+    background-color: var(--color-foreground-secondary);
+    color: var(--color-background-secondary);
+    font-size: 70%;
+    padding-left: 2px;
+    padding-right: 2px;
+    border-radius: 3px;
+    vertical-align: 15%;
+    padding-bottom: 2px;
+    filter: opacity(40%);
+}
+
+
+table.summarytable {
+    width: 100%;
+}

docs/_templates/autoapi/index.rst

@@ -0,0 +1,14 @@
+API Reference
+=============
+
+This page contains auto-generated API reference documentation.
+
+.. toctree::
+   :titlesonly:
+
+   {% for page in pages %}
+   {% if page.top_level_object and page.display %}
+   {{ page.include_path }}
+   {% endif %}
+   {% endfor %}
+

docs/_templates/autoapi/macros.rst

@@ -0,0 +1,68 @@
+{# AutoApiSummary replacement macro #}
+{#
+The intent of this macro is to replace the autoapisummary directive with the following
+improvements:
+1) Method signature is generated without typing annotation regardless of the value of
+   `autodoc_typehints`
+2) Properties are treated like attribute (but labelled as properties).
+3) Label are added as summary prefix to indicate if the member is a property, class
+   method, or static method.
+
+Copyright: Antoine Beyeler, 2022
+License: MIT
+#}
+
+{# Renders an object's name with a proper reference and optional signature.
+
+The signature is re-generated from obj.obj.args, which is undocumented but is the
+only way to have a type-less signature if `autodoc_typehints` is `signature` or
+`both`. #}
+{% macro _render_item_name(obj, sig=False) -%}
+:py:obj:`{{ obj.name }} <{{ obj.id }}>`
+     {%- if sig -%}
+       \ (
+       {%- for arg in obj.obj.args -%}
+          {%- if arg[0] %}{{ arg[0]|replace('*', '\*') }}{% endif -%}{{  arg[1] -}}
+          {%- if not loop.last  %}, {% endif -%}
+       {%- endfor -%}
+       ){%- endif -%}
+{%- endmacro %}
+
+
+{# Generates a single object optionally with a signature and a labe. #}
+{% macro _item(obj, sig=False, label='') %}
+   * - {{ _render_item_name(obj, sig) }}
+     - {% if label %}:summarylabel:`{{ label }}` {% endif %}{% if obj.summary %}{{ obj.summary }}{% else %}\-{% endif +%}
+{% endmacro %}
+
+
+
+{# Generate an autosummary-like table with the provided members. #}
+{% macro auto_summary(objs, title='') -%}
+
+.. list-table:: {{ title }}
+   :header-rows: 0
+   :widths: auto
+   :class: summarytable {#- apply CSS class to customize styling +#}
+
+  {% for obj in objs -%}
+    {#- should the full signature be used? -#}
+    {%- set sig = (obj.type in ['method', 'function'] and not 'property' in obj.properties) -%}
+
+    {#- compute label -#}
+    {%- if 'property' in obj.properties -%}
+      {%- set label = 'prop' -%}
+    {%- elif 'classmethod' in obj.properties -%}
+      {%- set label = 'class' -%}
+    {%- elif 'abstractmethod' in obj.properties -%}
+      {%- set label = 'abc' -%}
+    {%- elif 'staticmethod' in obj.properties -%}
+      {%- set label = 'static' -%}
+    {%- else -%}
+      {%- set label = '' -%}
+    {%- endif -%}
+
+    {{- _item(obj, sig=sig, label=label) -}}
+  {%- endfor -%}
+
+{% endmacro %}

docs/_templates/autoapi/python/class.rst

@@ -0,0 +1,69 @@
+{% import 'macros.rst' as macros %}
+
+{% if obj.display %}
+.. 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"] %}
+   .. autoapi-inheritance-diagram:: {{ obj.obj["full_name"] }}
+      :parts: 1
+      {% if "private-members" in autoapi_options %}
+      :private-bases:
+      {% endif %}
+
+   {% 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_attributes = obj.attributes|selectattr("display")|list %}
+   {% else %}
+   {% set visible_attributes = obj.attributes|rejectattr("inherited")|selectattr("display")|list %}
+   {% endif %}
+   {% 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 %}
+
+   {% if visible_methods or visible_attributes %}
+   .. rubric:: Overview
+
+   {% set summary_methods = visible_methods|rejectattr("properties", "contains", "property")|list %}
+   {% set summary_attributes = visible_attributes + visible_methods|selectattr("properties", "contains", "property")|list %}
+   {% if summary_attributes %}
+   {{ macros.auto_summary(summary_attributes, title="Attributes")|indent(3) }}
+   {% endif %}
+
+   {% if summary_methods %}
+   {{ macros.auto_summary(summary_methods, title="Methods")|indent(3) }}
+   {% endif %}
+
+   .. rubric:: Members
+
+   {% for attribute in visible_attributes %}
+   {{ attribute.render()|indent(3) }}
+   {% endfor %}
+   {% for method in visible_methods %}
+   {{ method.render()|indent(3) }}
+   {% endfor %}
+   {% endif %}
+{% endif %}

docs/_templates/autoapi/python/module.rst

@@ -0,0 +1,112 @@
+{% import 'macros.rst' as macros %}
+
+{% if not obj.display %}
+:orphan:
+
+{% endif %}
+{{ obj.name }}
+{{ "=" * obj.name|length }}
+
+.. py:module:: {{ obj.name }}
+
+{% if obj.docstring %}
+.. autoapi-nested-parse::
+
+   {{ obj.docstring|indent(3) }}
+
+{% endif %}
+
+{% block subpackages %}
+{% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
+{% if visible_subpackages %}
+Subpackages
+-----------
+.. toctree::
+   :titlesonly:
+   :maxdepth: 3
+
+{% for subpackage in visible_subpackages %}
+   {{ subpackage.short_name }}/index.rst
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+{% block submodules %}
+{% set visible_submodules = obj.submodules|selectattr("display")|list %}
+{% if visible_submodules %}
+Submodules
+----------
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+{% for submodule in visible_submodules %}
+   {{ submodule.short_name }}/index.rst
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+{% block content %}
+{% if obj.all is not none %}
+{% set visible_children = obj.children|selectattr("display")|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 %}
+Overview
+--------
+
+{% 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 %}
+{{ macros.auto_summary(visible_classes, title="Classes") }}
+{% endif %}
+{% endblock %}
+
+{% block functions scoped %}
+{% if visible_functions %}
+{{ macros.auto_summary(visible_functions, title="Function") }}
+{% endif %}
+{% endblock %}
+
+{% block attributes scoped %}
+{% if visible_attributes %}
+{{ macros.auto_summary(visible_attributes, title="Attributes") }}
+{% endif %}
+{% endblock %}
+{% endif %}
+
+{% if visible_classes %}
+Classes
+-------
+{% for obj_item in visible_classes %}
+{{ obj_item.render()|indent(0) }}
+{% endfor %}
+{% endif %}
+
+{% if visible_functions %}
+Functions
+---------
+{% for obj_item in visible_functions %}
+{{ obj_item.render()|indent(0) }}
+{% endfor %}
+{% endif %}
+
+{% if visible_attributes %}
+Attributes
+----------
+{% for obj_item in visible_attributes %}
+{{ obj_item.render()|indent(0) }}
+{% endfor %}
+{% endif %}
+
+
+{% endif %}
+{% endblock %}