Skip to content

Commit 126d72b

Browse files
zsquareplusczsquareplusc
committed
docs: add sphinx based docs
1 parent e0e11b1 commit 126d72b

File tree

8 files changed

+452
-4
lines changed

8 files changed

+452
-4
lines changed

‎README.rst‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,15 @@ Async I/O extension package for the Python Serial Port Extension for OSX, Linux,
77
It depends on pySerial and only provides the subpackage ``serial.aio`` which is
88
only compatible to Python 3.4 and newer.
99

10+
Documentation
11+
=============
1012

1113
Stable:
1214

13-
- Documentation: http://pythonhosted.org/pyserial/
14-
- Download Page: https://pypi.python.org/pypi/pyserial
15+
- Documentation: http://pythonhosted.org/pyserial-asyncio/
16+
- Download Page: https://pypi.python.org/pypi/pyserial-asyncio
1517

1618
Latest:
1719

18-
- Documentation: http://pyserial.readthedocs.io/en/latest/
19-
- Project Homepage: https://github.com/pyserial/pyserial
20+
- Documentation: http://pyserial-asyncio.readthedocs.io/en/latest/
21+
- Project Homepage: https://github.com/pyserial/pyserial-asyncio

‎documentation/Makefile‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
PAPER =
8+
9+
# Internal variables.
10+
PAPEROPT_a4 = -D latex_paper_size=a4
11+
PAPEROPT_letter = -D latex_paper_size=letter
12+
ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
13+
14+
.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
15+
16+
help:
17+
@echo "Please use \`make <target>' where <target> is one of"
18+
@echo " html to make standalone HTML files"
19+
@echo " dirhtml to make HTML files named index.html in directories"
20+
@echo " pickle to make pickle files"
21+
@echo " json to make JSON files"
22+
@echo " htmlhelp to make HTML files and a HTML help project"
23+
@echo " qthelp to make HTML files and a qthelp project"
24+
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
25+
@echo " changes to make an overview of all changed/added/deprecated items"
26+
@echo " linkcheck to check all external links for integrity"
27+
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
28+
29+
clean:
30+
-rm -rf _build/*
31+
32+
html:
33+
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
34+
@echo
35+
@echo "Build finished. The HTML pages are in _build/html."
36+
37+
dirhtml:
38+
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml
39+
@echo
40+
@echo "Build finished. The HTML pages are in _build/dirhtml."
41+
42+
pickle:
43+
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
44+
@echo
45+
@echo "Build finished; now you can process the pickle files."
46+
47+
json:
48+
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
49+
@echo
50+
@echo "Build finished; now you can process the JSON files."
51+
52+
htmlhelp:
53+
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
54+
@echo
55+
@echo "Build finished; now you can run HTML Help Workshop with the" \
56+
".hhp project file in _build/htmlhelp."
57+
58+
qthelp:
59+
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp
60+
@echo
61+
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
62+
".qhcp project file in _build/qthelp, like this:"
63+
@echo "# qcollectiongenerator _build/qthelp/pySerial.qhcp"
64+
@echo "To view the help file:"
65+
@echo "# assistant -collectionFile _build/qthelp/pySerial.qhc"
66+
67+
latex:
68+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
69+
@echo
70+
@echo "Build finished; the LaTeX files are in _build/latex."
71+
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
72+
"run these through (pdf)latex."
73+
74+
changes:
75+
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
76+
@echo
77+
@echo "The overview file is in _build/changes."
78+
79+
linkcheck:
80+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
81+
@echo
82+
@echo "Link check complete; look for any errors in the above output " \
83+
"or in _build/linkcheck/output.txt."
84+
85+
doctest:
86+
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest
87+
@echo "Testing of doctests in the sources finished, look at the " \
88+
"results in _build/doctest/output.txt."

‎documentation/api.rst‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
======================
2+
pySerial-asyncio API
3+
======================
4+
5+
asyncio
6+
=======
7+
8+
.. module:: serial.aio
9+
10+
.. warning:: This implementation is currently in an experimental state. Use
11+
at your own risk.
12+
13+
Experimental asyncio support is available for Python 3.4 and newer. The module
14+
:mod:`serial.aio` provides a :class:`asyncio.Transport`:
15+
``SerialTransport``.
16+
17+
18+
A factory function (`asyncio.coroutine`) is provided:
19+
20+
.. function:: create_serial_connection(loop, protocol_factory, \*args, \*\*kwargs)
21+
22+
:param loop: The event handler
23+
:param protocol_factory: Factory function for a :class:`asyncio.Protocol`
24+
:param args: Passed to the :class:`serial.Serial` init function
25+
:param kwargs: Passed to the :class:`serial.Serial` init function
26+
:platform: Posix
27+
28+
Get a connection making coroutine.
29+
30+
Example::
31+
32+
class Output(asyncio.Protocol):
33+
def connection_made(self, transport):
34+
self.transport = transport
35+
print('port opened', transport)
36+
transport.serial.rts = False
37+
transport.write(b'hello world\n')
38+
39+
def data_received(self, data):
40+
print('data received', repr(data))
41+
self.transport.close()
42+
43+
def connection_lost(self, exc):
44+
print('port closed')
45+
asyncio.get_event_loop().stop()
46+
47+
loop = asyncio.get_event_loop()
48+
coro = serial.aio.create_serial_connection(loop, Output, '/dev/ttyUSB0', baudrate=115200)
49+
loop.run_until_complete(coro)
50+
loop.run_forever()
51+
loop.close()
52+

‎documentation/appendix.rst‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
==========
2+
Appendix
3+
==========
4+
5+
License
6+
=======
7+
Copyright (c) 2015-2016 Chris Liechti <cliechti@gmx.net>
8+
All Rights Reserved.
9+
10+
Redistribution and use in source and binary forms, with or without
11+
modification, are permitted provided that the following conditions are
12+
met:
13+
14+
* Redistributions of source code must retain the above copyright
15+
notice, this list of conditions and the following disclaimer.
16+
17+
* Redistributions in binary form must reproduce the above
18+
copyright notice, this list of conditions and the following
19+
disclaimer in the documentation and/or other materials provided
20+
with the distribution.
21+
22+
* Neither the name of the copyright holder nor the names of its
23+
contributors may be used to endorse or promote products derived
24+
from this software without specific prior written permission.
25+
26+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
27+
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
28+
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
29+
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
30+
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
31+
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
32+
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
33+
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
34+
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
35+
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
36+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37+

0 commit comments

Comments
 (0)