Browse Source

Added Sphinx documentation

I'm finally blossoming into a mature Python developer.
Clara Hobbs 2 years ago
parent
commit
dda9d3f0f8
5 changed files with 291 additions and 0 deletions
  1. 1
    0
      alpaca_isp/chips.py
  2. 34
    0
      doc/source/alpaca_isp.rst
  3. 48
    0
      doc/source/alpaca_isp_api.rst
  4. 179
    0
      doc/source/conf.py
  5. 29
    0
      doc/source/index.rst

+ 1
- 0
alpaca_isp/chips.py View File

@@ -35,6 +35,7 @@ class Chip(namedtuple("Chip", [
35 35
         "max_copy",
36 36
         # Sector table
37 37
         "sectors"])):
38
+    """Flashing-related properties of an LPC microcontroller"""
38 39
     __slots__ = ()
39 40
 
40 41
     @property

+ 34
- 0
doc/source/alpaca_isp.rst View File

@@ -0,0 +1,34 @@
1
+alpaca_isp Command-Line Tool
2
+============================
3
+
4
+::
5
+
6
+    usage: alpaca_isp [-h] [-b BAUDRATE] [-c CLOCK_KHZ] [-t TIMEOUT] [-e]
7
+                      [--no-start] [--try-sync TRY_SYNC] [-n] [-r]
8
+                      file [file ...] tty
9
+    
10
+    Flash an LPC microcontroller
11
+    
12
+    positional arguments:
13
+      file                  Intel HEX file to flash to the microcontroller
14
+      tty                   the tty to which the microcontroller is attached
15
+    
16
+    optional arguments:
17
+      -h, --help            show this help message and exit
18
+      -b BAUDRATE, --baudrate BAUDRATE
19
+                            baud rate used for communication (default: 115200)
20
+      -c CLOCK_KHZ, --clock-khz CLOCK_KHZ
21
+                            microcontroller's clock frequency in kHz (default:
22
+                            12000)
23
+      -t TIMEOUT, --timeout TIMEOUT
24
+                            timeout for reading data from the microcontroller in
25
+                            seconds (default: 0.1)
26
+      -e, --erase           erase all the microcontroller's flash before flashing
27
+      --no-start            do not start the microcontroller after flashing
28
+      --try-sync TRY_SYNC   maximum number of tries to synchronize with the
29
+                            microcontroller
30
+      -n, --control         control RS232 lines to enter ISP mode (/RST = DTR,
31
+                            /ISP = RTS)
32
+      -r, --verify          verify that the data were written correctly after
33
+                            flashing
34
+

+ 48
- 0
doc/source/alpaca_isp_api.rst View File

@@ -0,0 +1,48 @@
1
+alpaca_isp API
2
+==============
3
+
4
+.. module:: alpaca_isp
5
+
6
+.. automodule:: alpaca_isp
7
+   :members:
8
+
9
+LPC
10
+---
11
+
12
+.. autoclass:: LPC
13
+   :members:
14
+
15
+.. autoclass:: LPC8xx
16
+   :members:
17
+
18
+.. autoclass:: ReturnCode
19
+   :members:
20
+
21
+.. data:: DEFAULT_BAUDRATE
22
+
23
+.. data:: DEFAULT_CLOCK
24
+
25
+.. data:: DEFAULT_TIMEOUT
26
+
27
+Chips
28
+-----
29
+
30
+.. module:: alpaca_isp
31
+
32
+.. data:: chips
33
+
34
+   A dict mapping chip ID numbers to :class:`chips.Chip` objects describing their attributes
35
+
36
+.. module:: alpaca_isp.chips
37
+
38
+.. autoclass:: Chip
39
+   :members:
40
+
41
+Exceptions
42
+----------
43
+
44
+.. autoclass:: alpaca_isp.ISPError
45
+   :members:
46
+
47
+.. autoclass:: alpaca_isp.RecvTimeout
48
+   :members:

+ 179
- 0
doc/source/conf.py View File

@@ -0,0 +1,179 @@
1
+#!/usr/bin/env python3
2
+# -*- coding: utf-8 -*-
3
+#
4
+# alpaca_isp documentation build configuration file, created by
5
+# sphinx-quickstart on Mon Apr 16 19:26:33 2018.
6
+#
7
+# This file is execfile()d with the current directory set to its
8
+# containing dir.
9
+#
10
+# Note that not all possible configuration values are present in this
11
+# autogenerated file.
12
+#
13
+# All configuration values have a default; values that are commented out
14
+# serve to show the default.
15
+
16
+# If extensions (or modules to document with autodoc) are in another directory,
17
+# add these directories to sys.path here. If the directory is relative to the
18
+# documentation root, use os.path.abspath to make it absolute, like shown here.
19
+#
20
+# import os
21
+# import sys
22
+# sys.path.insert(0, os.path.abspath('.'))
23
+import os
24
+import sys
25
+sys.path.insert(0, os.path.abspath('..'))
26
+
27
+import alpaca_isp
28
+
29
+
30
+# -- General configuration ------------------------------------------------
31
+
32
+# If your documentation needs a minimal Sphinx version, state it here.
33
+#
34
+# needs_sphinx = '1.0'
35
+
36
+# Add any Sphinx extension module names here, as strings. They can be
37
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
38
+# ones.
39
+extensions = ['sphinx.ext.autodoc',
40
+    'sphinx.ext.intersphinx',
41
+    'sphinx.ext.ifconfig']
42
+
43
+# Add any paths that contain templates here, relative to this directory.
44
+templates_path = ['_templates']
45
+
46
+# The suffix(es) of source filenames.
47
+# You can specify multiple suffix as a list of string:
48
+#
49
+# source_suffix = ['.rst', '.md']
50
+source_suffix = '.rst'
51
+
52
+# The master toctree document.
53
+master_doc = 'index'
54
+
55
+# General information about the project.
56
+project = 'alpaca_isp'
57
+copyright = '2018, Clayton G. Hobbs'
58
+author = 'Clayton G. Hobbs'
59
+
60
+# The version info for the project you're documenting, acts as replacement for
61
+# |version| and |release|, also used in various other places throughout the
62
+# built documents.
63
+#
64
+# The short X.Y version.
65
+version = alpaca_isp.__version__
66
+# The full version, including alpha/beta/rc tags.
67
+release = version
68
+
69
+# The language for content autogenerated by Sphinx. Refer to documentation
70
+# for a list of supported languages.
71
+#
72
+# This is also used if you do content translation via gettext catalogs.
73
+# Usually you set "language" from the command line for these cases.
74
+language = None
75
+
76
+# List of patterns, relative to source directory, that match files and
77
+# directories to ignore when looking for source files.
78
+# This patterns also effect to html_static_path and html_extra_path
79
+exclude_patterns = []
80
+
81
+# The name of the Pygments (syntax highlighting) style to use.
82
+pygments_style = 'sphinx'
83
+
84
+# If true, `todo` and `todoList` produce output, else they produce nothing.
85
+todo_include_todos = False
86
+
87
+
88
+# -- Options for HTML output ----------------------------------------------
89
+
90
+# The theme to use for HTML and HTML Help pages.  See the documentation for
91
+# a list of builtin themes.
92
+#
93
+html_theme = 'alabaster'
94
+
95
+# Theme options are theme-specific and customize the look and feel of a theme
96
+# further.  For a list of options available for each theme, see the
97
+# documentation.
98
+#
99
+# html_theme_options = {}
100
+
101
+# Add any paths that contain custom static files (such as style sheets) here,
102
+# relative to this directory. They are copied after the builtin static files,
103
+# so a file named "default.css" will overwrite the builtin "default.css".
104
+html_static_path = ['_static']
105
+
106
+# Custom sidebar templates, must be a dictionary that maps document names
107
+# to template names.
108
+#
109
+# This is required for the alabaster theme
110
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
111
+html_sidebars = {
112
+    '**': [
113
+        'relations.html',  # needs 'show_related': True theme option to display
114
+        'searchbox.html',
115
+    ]
116
+}
117
+
118
+
119
+# -- Options for HTMLHelp output ------------------------------------------
120
+
121
+# Output file base name for HTML help builder.
122
+htmlhelp_basename = 'alpaca_ispdoc'
123
+
124
+
125
+# -- Options for LaTeX output ---------------------------------------------
126
+
127
+latex_elements = {
128
+    # The paper size ('letterpaper' or 'a4paper').
129
+    #
130
+    # 'papersize': 'letterpaper',
131
+
132
+    # The font size ('10pt', '11pt' or '12pt').
133
+    #
134
+    # 'pointsize': '10pt',
135
+
136
+    # Additional stuff for the LaTeX preamble.
137
+    #
138
+    # 'preamble': '',
139
+
140
+    # Latex figure (float) alignment
141
+    #
142
+    # 'figure_align': 'htbp',
143
+}
144
+
145
+# Grouping the document tree into LaTeX files. List of tuples
146
+# (source start file, target name, title,
147
+#  author, documentclass [howto, manual, or own class]).
148
+latex_documents = [
149
+    (master_doc, 'alpaca_isp.tex', 'alpaca\\_isp Documentation',
150
+     'Clayton G. Hobbs', 'manual'),
151
+]
152
+
153
+
154
+# -- Options for manual page output ---------------------------------------
155
+
156
+# One entry per manual page. List of tuples
157
+# (source start file, name, description, authors, manual section).
158
+man_pages = [
159
+    (master_doc, 'alpaca_isp', 'alpaca_isp Documentation',
160
+     [author], 1)
161
+]
162
+
163
+
164
+# -- Options for Texinfo output -------------------------------------------
165
+
166
+# Grouping the document tree into Texinfo files. List of tuples
167
+# (source start file, target name, title, author,
168
+#  dir menu entry, description, category)
169
+texinfo_documents = [
170
+    (master_doc, 'alpaca_isp', 'alpaca_isp Documentation',
171
+     author, 'alpaca_isp', 'One line description of project.',
172
+     'Miscellaneous'),
173
+]
174
+
175
+
176
+
177
+
178
+# Example configuration for intersphinx: refer to the Python standard library.
179
+intersphinx_mapping = {'https://docs.python.org/': None}

+ 29
- 0
doc/source/index.rst View File

@@ -0,0 +1,29 @@
1
+.. alpaca_isp documentation master file, created by
2
+   sphinx-quickstart on Mon Apr 16 19:26:33 2018.
3
+   You can adapt this file completely to your liking, but it should at least
4
+   contain the root `toctree` directive.
5
+
6
+Welcome to alpaca_isp's documentation!
7
+======================================
8
+
9
+alpaca_isp is an in-system programming tool for LPC microcontrollers.  It
10
+provides a Pythonic interface to the LPC ISP command handler, as well as a
11
+convenient command-line interface for flashing from build systems.  It can put
12
+microcontrollers into ISP mode by manipulating the serial port's DTR (/RST) and
13
+RTS (/ISP) lines.
14
+
15
+.. toctree::
16
+   :maxdepth: 2
17
+   :caption: Contents:
18
+
19
+   alpaca_isp
20
+   alpaca_isp_api
21
+
22
+
23
+
24
+Indices and tables
25
+==================
26
+
27
+* :ref:`genindex`
28
+* :ref:`modindex`
29
+* :ref:`search`

Loading…
Cancel
Save