Skip to content

Commit 031dc44

Browse files
felix-andreasfelix-andreas
authored
add Documenation (#11)
- Use Sphinx to create Documentation. - API Reference is generated by readthedocs's sphinx_autoapi
1 parent 33f8ced commit 031dc44

File tree

17 files changed

+840
-1
lines changed

17 files changed

+840
-1
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
[![Python Version](https://img.shields.io/pypi/pyversions/apace)](https://pypi.org/project/apace/)
33
[![PyPI](https://img.shields.io/pypi/v/apace.svg)](https://pypi.org/project/apace/)
44
[![CI](https://github.com/andreasfelix/apace/workflows/CI/badge.svg)](https://github.com/andreasfelix/apace/actions?query=workflow%3ACI)
5-
[![Docs](https://readthedocs.org/projects/apace/badge/?version=latest)](https://apace.readthedocs.io/en/docs/)
5+
[![Docs](https://readthedocs.org/projects/apace/badge/?version=latest)](https://apace.readthedocs.io)
66

77
**apace** is yet **a**nother **p**article **a**ccelerator **c**od**e** designed for the optimization of beam optics. It is available as Python package and aims to provide a convenient and straightforward API to make use of Python's numerous scientific libraries.
88

‎docs/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
_build
2+
generated

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/_static/.gitkeep‎

Whitespace-only changes.

‎docs/_templates/.gitkeep‎

Whitespace-only changes.

‎docs/_templates/autoapi/index.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
API Reference
2+
=============
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
:titlesonly:
7+
8+
{% for page in pages %}
9+
{% if page.top_level_object and page.display %}
10+
{{ page.include_path }}
11+
{% endif %}
12+
{% endfor %}

‎docs/_templates/autoapi/python/class.rst‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
{% if obj.display %}
2+
.. py:{{ obj.type }}:: {{ obj.short_name }}{% if obj.args %}({{ obj.args }}){% endif %}
3+
4+
5+
{% if obj.bases %}
6+
Inherits: {% for base in obj.bases %}:class:`{{ base }}`{% if not loop.last %}, {% endif %}{% endfor %}
7+
8+
{% endif %}
9+
10+
{% if obj.docstring %}
11+
{{ obj.docstring|prepare_docstring|indent(3) }}
12+
{% endif %}
13+
{% set visible_classes = obj.classes|selectattr("display")|list %}
14+
{% for klass in visible_classes %}
15+
{{ klass.rendered|indent(3) }}
16+
{% endfor %}
17+
18+
{% set visible_attributes = obj.attributes|selectattr("display")|rejectattr("annotation", "equalto", "Signal")|list %}
19+
{% set visible_signals = obj.attributes|selectattr("display")|selectattr("annotation", "equalto", "Signal")|list %}
20+
{% set visible_methods = [] %}
21+
{% for method in obj.methods|selectattr("display")|list %}
22+
{% if "property" in method.properties %}
23+
{% set _ = visible_attributes.append(method) %}
24+
{% else %}
25+
{% set _ = visible_methods.append(method) %}
26+
{% endif %}
27+
{% endfor %}
28+
29+
{% if visible_attributes %}
30+
**Attributes**
31+
{% endif %}
32+
33+
{% for attribute in visible_attributes %}
34+
{{ attribute.rendered|indent(3) }}
35+
{% endfor %}
36+
37+
{% if visible_methods %}
38+
**Methods**
39+
{% endif %}
40+
41+
{% for method in visible_methods %}
42+
{{ method.rendered|indent(3) }}
43+
{% endfor %}
44+
45+
{% if visible_signals %}
46+
**Signals**
47+
{% endif %}
48+
49+
{% for signal in visible_signals %}
50+
{{ signal.rendered|indent(3) }}
51+
{% endfor %}
52+
53+
{% endif %}

‎docs/_templates/autoapi/python/method.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{%- if obj.display %}
2+
{% if sphinx_version >= (2, 1) %}
3+
{% if "property" in obj.properties %}
4+
.. attribute:: {{ obj.short_name }}
5+
{%+ if obj.return_annotation %}:annotation: :{{ obj.return_annotation }}{% endif %}
6+
{% else %}
7+
.. method:: {{ obj.short_name }}({{ obj.args.split(',', 1)[1:]|join(',') }}) {% if obj.return_annotation %} -> {{ obj.return_annotation }}{% endif %}
8+
{% for property in obj.properties %}
9+
:{{ property }}:
10+
{% endfor %}
11+
{% endif %}
12+
13+
{% else %}
14+
.. {{ obj.method_type }}:: {{ obj.short_name }}({{ obj.args.split(',', 1)[1:]|join(',') }})
15+
{% endif %}
16+
17+
{% if obj.docstring %}
18+
{{ obj.docstring|prepare_docstring|indent(3) }}
19+
{% endif %}
20+
{% endif %}

‎docs/_templates/autoapi/python/package.rst‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
{% if not obj.display %}
2+
:orphan:
3+
4+
{% endif %}
5+
6+
.. _api-reference:
7+
8+
API Reference
9+
=============
10+
11+
This is the API reference. To learn how to use and work with apace, see :ref:`user-guide`.
12+
13+
{% if obj.docstring %}
14+
.. autoapi-nested-parse::
15+
16+
{{ obj.docstring|prepare_docstring|indent(3) }}
17+
18+
{% endif %}
19+
20+
{% if obj.all is not none %}
21+
{% set visible_children = obj.children|selectattr("short_name", "in", obj.all)|list %}
22+
{% elif obj.type is equalto("package") %}
23+
{% set visible_children = obj.children|selectattr("display")|list %}
24+
{% else %}
25+
{% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %}
26+
{% endif %}
27+
{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %}
28+
{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %}
29+
{% set visible_exceptions = visible_children|selectattr("type", "equalto", "exception")|list %}
30+
{% set constants = obj.children|selectattr("type", "equalto", "data")|list %}
31+
32+
Classes
33+
-------
34+
{% for klass in obj.classes %}
35+
* :class:`{{ klass.name }}` - {{ klass.summary }}
36+
{% endfor %}
37+
38+
Functions
39+
---------
40+
{% for function in obj.functions %}
41+
* :func:`{{ function.name }}` - {{ function.summary }}
42+
{% endfor %}
43+
44+
Exceptions
45+
----------
46+
{% for exception in visible_exceptions %}
47+
* :exc:`{{ exception.name }}` - {{ exception.summary }}
48+
{% endfor %}
49+
50+
Constants
51+
---------
52+
{% for constant in constants %}
53+
* :const:`{{ constant.name }}` **=** :code:`{{ constant.value }}`
54+
{% endfor %}
55+
56+
Detailed Overview
57+
-----------------
58+
{% for obj in visible_classes %}
59+
{{ obj.rendered|indent(0) }}
60+
{% endfor %}
61+
62+
{% for obj in visible_functions %}
63+
{{ obj.rendered|indent(0) }}
64+
{% endfor %}
65+
66+
{% for obj in visible_exceptions %}
67+
{{ obj.rendered|indent(0) }}
68+
{% endfor %}
69+
70+

‎docs/cli.rst‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
Command line tool
2+
*****************
3+
4+
**apace** also has a simple command line tool which gets automatically installed when installing with pip. This tool is currently work in progress, but the calculation of the Twiss parameter should already be functioning.
5+
6+
Installing the CLI
7+
==================
8+
9+
The **apace-cli** should be already available if apace was installed using pip. It can be invoked from the command line via::
10+
11+
apace
12+
13+
Getting Help
14+
============
15+
16+
To get help use the :code:`--help` flag,
17+
18+
.. code::
19+
20+
apace --help
21+
22+
which should output something like this:
23+
24+
.. code:: text
25+
26+
usage: apace [-h] [--version] {help,twiss,convert} ...
27+
28+
This is the apace CLI.
29+
30+
positional arguments:
31+
{help,twiss,convert}
32+
help Get help
33+
twiss plot or save twiss functions to file
34+
convert convert lattice files.
35+
36+
optional arguments:
37+
-h, --help show this help message and exit
38+
--version show program's version number and exit
39+
40+
41+
42+
43+
The twiss subcommand
44+
====================
45+
46+
Plot Twiss parameter for a given lattice:
47+
48+
.. code:: sh
49+
50+
apace twiss path/to/lattice.json
51+
52+
Other options:
53+
54+
.. code::
55+
56+
usage: apace twiss [-h] [-o OUTPUT_PATH] [-v] [-q] [-show]
57+
[-ref REF_LATTICE_PATH] [-y_min Y_MIN] [-y_max Y_MAX]
58+
[-s SECTIONS] [-pos POSITIONS] [-m MULTI_KNOB]
59+
path [path ...]
60+
61+
positional arguments:
62+
path Path to lattice file or directory with lattice files.
63+
64+
optional arguments:
65+
-h, --help show this help message and exit
66+
-o OUTPUT_PATH, --output_path OUTPUT_PATH
67+
Output path for plot
68+
-v, --verbose Verbose
69+
-q, --quiet Quiet
70+
-show, --show_plot show interactive plot
71+
-ref REF_LATTICE_PATH, --ref_lattice_path REF_LATTICE_PATH
72+
Path to reference lattice
73+
-y_min Y_MIN Min Y-value
74+
-y_max Y_MAX Max Y-value
75+
-s SECTIONS, --sections SECTIONS
76+
Plot Twiss parameter at given sections. Can be a
77+
2-tuple (START, END), the name of the section or
78+
sequence those '[(START, END), SECTION_NAME, ...]'.
79+
-pos POSITIONS, --positions POSITIONS
80+
Print Twiss parameter at given positions. Can be a
81+
number, a 2-tuple (START, END), a section name or
82+
sequence of those.
83+
-m MULTI_KNOB, --multi_knob MULTI_KNOB
84+
Multi-knob (Assumes plot)
85+
86+
87+
88+

0 commit comments

Comments
 (0)