Document how to updated the docs
Opened this issue · 21 comments
I've tried to figure this out but now I am stuck.
I installed all dev requirments sudo pip install -r requirements-dev.txt
In docs I did gmake pdf which gave a bunch of errors that it couldn't find nodeserver_api.py methods, so I edited docs/conf.py and added sys.path.insert(0, os.path.abspath('..')) to resolve those, but now it dies with:
pi@rpi2:~/development/Polyglot/docs $ make pdf
sphinx-build -b pdf -d _build/doctrees . _build/pdf
Running Sphinx v1.4.1
loading translations [en]... done
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [pdf]: targets for 5 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
processing Polyglot... index usage nsdev nsexample nsapi [ERROR] pdfbuilder.py:130 too many values to unpack
Traceback (most recent call last):
File "/usr/local/lib/python2.7/dist-packages/rst2pdf/pdfbuilder.py", line 122, in write
appendices=opts.get('pdf_appendices', self.config.pdf_appendices) or [])
File "/usr/local/lib/python2.7/dist-packages/rst2pdf/pdfbuilder.py", line 209, in assemble_doctree
index_nodes=genindex_nodes(genindex)
File "/usr/local/lib/python2.7/dist-packages/rst2pdf/pdfbuilder.py", line 385, in genindex_nodes
for entryname, (links, subitems) in entries:
ValueError: too many values to unpack
FAILED
I've never used this method before so we need someone familiar with this to document how to update the documentation and regenerate everything.
I re-ran sudo pip install -r requirements-dev.txt just to make sure everything was correct, and it uninstalled the versions I already had of a few modules and installed new versions:
Found existing installation: Sphinx 1.4.1
Uninstalling Sphinx:
Successfully uninstalled Sphinx
Found existing installation: rst2pdf 0.93.dev-r0
Uninstalling rst2pdf:
Successfully uninstalled rst2pdf
Running setup.py install for rst2pdf
and now 'make pdf' works. Although it spits out a bunch of text that looks like it should be part of the documentation and I have no idea if this is normal or not.
pi@rpi2:~/development/Polyglot/docs $ make pdf
sphinx-build -b pdf -d _build/doctrees . _build/pdf
Running Sphinx v1.3.1
loading translations [en]... done
loading pickled environment... failed: 'module' object has no attribute 'Symbol'
building [mo]: targets for 0 po files that are out of date
building [pdf]: targets for 5 source files that are out of date
updating environment: 5 added, 0 changed, 0 removed
reading sources... [100%] usage
/home/pi/development/Polyglot/polyglot/nodeserver_api.py:docstring of polyglot.nodeserver_api.Node:9: WARNING: Field list ends without a blank line; unexpected unindent.
/home/pi/development/Polyglot/polyglot/nodeserver_api.py:docstring of polyglot.nodeserver_api.NodeServer.poly:4: WARNING: Field list ends without a blank line; unexpected unindent.
/home/pi/development/Polyglot/polyglot/nodeserver_api.py:docstring of polyglot.nodeserver_api.SimpleNodeServer.add_node:4: WARNING: Field list ends without a blank line; unexpected unindent.
/home/pi/development/Polyglot/polyglot/nodeserver_api.py:docstring of polyglot.nodeserver_api.SimpleNodeServer.exist_node:4: WARNING: Field list ends without a blank line; unexpected unindent.
/home/pi/development/Polyglot/polyglot/nodeserver_api.py:docstring of polyglot.nodeserver_api.SimpleNodeServer.get_node:4: WARNING: Field list ends without a blank line; unexpected unindent.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
processing Polyglot... index usage nsdev nsexample nsapi <string>:7: (WARNING/2) Duplicate explicit target name: "(polyglot.nodeserver_api.simplenodeserver method)".
<string>:7: (WARNING/2) Duplicate explicit target name: "(polyglot.nodeserver_api.simplenodeserver method)".
<string>:7: (WARNING/2) Duplicate explicit target name: "(polyglot.nodeserver_api.simplenodeserver method)".
<string>:7: (WARNING/2) Duplicate explicit target name: "(polyglot.nodeserver_api.simplenodeserver method)".
<string>:7: (WARNING/2) Duplicate explicit target name: "(polyglot.nodeserver_api.simplenodeserver method)".
<string>:7: (WARNING/2) Duplicate explicit target name: "(polyglot.nodeserver_api.simplenodeserver method)".
<string>:7: (WARNING/2) Duplicate explicit target name: "(polyglot.nodeserver_api.simplenodeserver method)".
<string>:7: (WARNING/2) Duplicate explicit target name: "(polyglot.nodeserver_api.simplenodeserver method)".
py-modindex
resolving references...
done
writing Polyglot... [WARNING] styles.py:548 Using undefined style 'function', aliased to style 'normal'.
<line><emphasis>{'config': {... arbitrary data saved by the node server ...}}</emphasis></line> line
<line>This command is the first one sent to the node server and is only sent
once. The arguments dictionary will be of an arbitrary structure and will
match what the Node Server had last saved.</line> line
<line><emphasis>{'install': {'profile_number': ...}}</emphasis></line> line
<line>Instructs the node server to install itself with the specified
<emphasis>profile_number</emphasis>.</line> line
<line><emphasis>{'query': {'node_address': ..., 'request_id': ...}}</emphasis></line> line
<line>Instructs the node server to query a node. <emphasis>request_id</emphasis> is optional.</line> line
<line><emphasis>{'status': {'node_address': ..., 'request_id': ...}}</emphasis></line> line
<line>Requests the node server to send current node status to the ISY.
<emphasis>request_id</emphasis> is optional.</line> line
<line><emphasis>{'add_all': {'request_id': ...}}</emphasis></line> line
<line>Requests that the node server add all its nodes to the ISY.
<emphasis>request_id</emphasis> is optional.</line> line
<line><emphasis>{'added': {'node_address': ..., 'node_def_id': ..., 'primary_node_address': ..., 'name': ...}}</emphasis></line> line
<line>Indicates that the node has been added to the ISY.</line> line
<line><emphasis>{'removed': {'node_address': ...}}</emphasis></line> line
<line>Indicates that the node has been removed from the ISY.</line> line
<line><emphasis>{'renamed': {'node_address': ..., 'name': ...}}</emphasis></line> line
<line>Indicates that the node has been renamed in the ISY.</line> line
<line><emphasis>{'enabled': {'node_address': ...}}</emphasis></line> line
<line>Indicates that the node has been enabled in the ISY.</line> line
<line><emphasis>{'disabled': {'node_address': ...}}</emphasis></line> line
<line>Indicates that the node has been disabled in the ISY.</line> line
<line><emphasis>{'cmd': {'node_address': ..., 'command': ..., *'value': ...., *'uom': ..., *'<pn>.<uomn>': ..., *'request_id': ...}}</emphasis></line> line
<line>Instructs the node server to run the specified command on the specified
node. <emphasis>value</emphasis> and <emphasis>uom</emphasis> are optional and described the unnamed parameter.
They will always appear together. <emphasis><pn>.<uomn></emphasis> will be repeated as
necessary to described the unnamed parameters. They are also optional.
<emphasis>request_id</emphasis> is optional.</line> line
<line><emphasis>{'ping': {}}</emphasis></line> line
<line>This is a command from Polyglot requesting a Pong response. This is handled
in the PolyglotConnector class.</line> line
<line><emphasis>{'exit': {}}</emphasis></line> line
<line>This command is Polyglot instructing the node server to cleanly shut down.</line> line
<line><emphasis>{'config': {... arbitrary data saved by the node server ...}}</emphasis></line> line
<line>Sends configuration data to Polyglot to be saved. This data will be sent
back to the Node Server, exactly as it has been sent to Polyglot, the next
time the Node Server is started.</line> line
<line><emphasis>{'install': {}}</emphasis></line> line
<line>Install the node server on the ISY. This has not been implemented yet.</line> line
<line><emphasis>{'status': {'node_address': ..., 'driver_control': ..., 'value': ..., 'uom': ...}}</emphasis></line> line
<line>Reports a node's driver status.</line> line
<line><emphasis>{'command': {'node_address': ..., 'command', ..., 'value': ...., 'uom': ..., '<pn>.<uomn>': ...}}</emphasis></line> line
<line>Reports that a command has been run on a node. <emphasis>value</emphasis> and <emphasis>uom</emphasis> are
optional and described the unnamed parameter. They will always appear
together. <emphasis><pn>.<uomn></emphasis> will be repeated as necessary to described the
unnamed parameters. They are also optional.</line> line
<line><emphasis>{'add': {'node_address': ..., 'node_def_id': ..., 'primary': ..., 'name': ...}}</emphasis></line> line
<line>Adds a node to the ISY.</line> line
<line><emphasis>{'change': {'node_address': ..., 'node_def_id': ...}}</emphasis></line> line
<line>Changes the node's definition in the ISY.</line> line
<line><emphasis>{'remove': {'node_address': ...}}</emphasis></line> line
<line>Instructs the ISY to remove a node.</line> line
<line><emphasis>{'request': {'request_id': ..., 'result': ...}}</emphasis></line> line
<line>Replies to the ISY indicating that a request has been finished either
successfully or unsuccessfully. The result parameter must be a boolean
indicating this.</line> line
<line><emphasis>{'pong': {}}</emphasis></line> line
<line>The proper response to a Ping command. Must be recieved within 30 seconds
of a Ping command or Polyglot assumes the Node Server has stalled and
kills it. This is handled automatically in the PolyglotConnector class.</line> line
<line><emphasis>{'exit': {}}</emphasis></line> line
<line>Indicates to Polyglot that the node server has exited and is now closing.
This is the last message sent from a node server. All messages following
this will be ignored. It is not guaranteed that the node server process
will continue to run after this command is sent.</line> line
done
build succeeded, 5 warnings.
Build finished. The PDF files are in _build/pdf.
Hi Jim,
Thank you.
What branch? I cannot find a build directory so I do not know where the PDF is. Can you please send me a link?
jimboca: Removed included email, Michel, please comment thru the github link or edit your email to not include the original text. Really surprised that github doesn't handle it properly...
The original documentation is all in docs directory and all branches have the original pdf: https://github.com/UniversalDevicesInc/Polyglot/blob/master/docs/_build/pdf/Polyglot.pdf
I have started the documentation here: https://github.com/UniversalDevicesInc/Polyglot/wiki/Build-and-Release-Information#updating-documentation
But, I really don't want to be responsible for figuring all this out so I would like someone to take it over!
Looks fantastic. Thanks so very much!
With kind regards,
Michel Kohanim
CEO
(p) 818.631.0333
(f) 818.436.0702
http://www.universal-devices.comhttp://www.universal-devices.com/
From: jimboca [mailto:notifications@github.com]
Sent: Friday, April 15, 2016 10:04 AM
To: UniversalDevicesInc/Polyglot Polyglot@noreply.github.com
Cc: Michel Kohanim michel@universal-devices.com
Subject: Re: [UniversalDevicesInc/Polyglot] Document how to updated the docs (#43)
The original documentation is all in docs directory and all branches have the original pdf: https://github.com/UniversalDevicesInc/Polyglot/blob/master/docs/_build/pdf/Polyglot.pdf
—
You are receiving this because you commented.
Reply to this email directly or view it on GitHubhttps://github.com//issues/43#issuecomment-210548493
Thanks Michel, so are you going to take over formalizing this and making sure it works properly?
Also, when replying to github emails, please remove the original email from your response since github does not automatically handle that. Or, better yet, click on the like to comment directly on github.
BTW, let's not commit generated docs to git, except on the development branch (and the release branch) -- there's no point to merging generated files in the first place, plus it really obfuscates the real changes we make.
(Frankly, IMO we shouldn't have ANY generated code -- documentation nor .pyz files -- in the SOURCE code repository! :) Released binary download packages should be saved elsewhere. But that's an opinion, and to some degree "water under the bridge" at this point...)
I completely agree, but as you mention it was water under the bridge so I didn't mention it because I was not sure what should be done about it and just followed what was already being done.
I asked Michel on another issue to create a separate repo for the generated artifacts (docs as well as pyz files) -- after thinking about it for a while, I don't think we're so far along that we can't separate things.
Sounds good to me, if that is standard way of handling distributing generated files 👍
I added a note about setting the documentation version, someone will need to figure out the proper way to set the docs/conf.py version and release variables. https://github.com/UniversalDevicesInc/Polyglot/wiki/Build-and-Release-Information
@mjwesterhof , I am OK with creating another repository. Please do let me know.
With kind regards,
Michel
Hi Jim,
With regards to the documentation, I am asking Brad to take a look.
With kind regards,
Michel
http://www.sphinx-doc.org/en/stable/tutorial.html << here is a guide for this. I finally found it :)
Hi James,
Thanks so very much. Brad is still looking into it (learning from scratch).
With kind regards,
Michel
No problem, so am I!
Ok boys and girls. Documentation is updated and started. I need you to update and add your documentation to the 'development' branch. Inside your methods wrap a definition inside triple quotations. For example:
class Node(object):
"""
Abstract class for representing a node in a node server.
:param parent: The node server that controls the node
:type parent: polyglot.nodeserver_api.NodeServer
:param str address: The address of the node in the ISY without the node
server ID prefix
:param str name: The name of the node
:param primary: The primary node for the device this node belongs to,
: or True if it's the primary.
:type primary: polyglot.nodeserver_api.Node or True if this node is the primary.
:param manifest: The node manifest saved by the node server
:type manifest: dict or None
.. document private methods
.. autoattribute:: _drivers
.. autoattribute:: _commands
"""
def __init__(self, parent, address, name, primary=True, manifest=None):
Secondly if you want to explain something, please do so in the .rst files inside the docs folder.
Full documentation as it stands
Once you commit and push to the development branch, these docs are AUTOMATICALLY updated. Usually takes about 4-5 minutes. This is done using the Sphinx way. Read up on Sphinx and get to documenting any and ALL changes you have made since the inception of the github repo. I would like for these to be extremely detailed please.
Thanks,
E
Great job getting this all setup and working! I will review my changes and make sure the docs are updated.
I tried to make it as easy as possible, so hopefully we can keep up with it. Happy holiday.
@mjwesterhof @jimboca I'm updating the documents again and adding a changelog.rst file that we will track changes made in each version. I will be releasing 0.0.6 to development shortly, after I do so, please edit that changelog.rst file and add anything you have done in 0.0.4 and 0.0.5, I can't remember everything we did there. I'm especially interested in the pulse documentation as I don't see that anywhere and we need to get it documented.
-E
@Einstein42 Thanks, I'll look thru and add anything. @mjwesterhof yes, the pulse docs would be great, I had added that to the camera node server, but pulled it out since the changes had not been pushed yet.