docs: improve doc generation and contents

AUTHORS.rst

@@ -2,4 +2,4 @@
 Developers
 ==========
 
-* Anderson Bravalheri <andersonbravalherigmail.com>
+* Anderson Bravalheri <andersonbravalheri@gmail.com>

CHANGES.rst

@@ -2,9 +2,38 @@
 Changelog
 =========
 
-Version 0.1
-===========
+Version 0.0.1 (2016-06-01)
+==========================
 
-- Feature A added
-- FIX: nasty bug #1729 fixed
-- add your changes here!
+Features
+--------
+
+- **ast:**
+-  add select, find, from\_tuple, append
+   (`67724329 <https://github.com/abravalheri/pyangext/commit/67724329d8383404863f9c6f7aa5496ba9c90bd9>`__)
+-  add walk function to traverse tree
+   (`1f334d3d <https://github.com/abravalheri/pyangext/commit/1f334d3deaccd12366f110ec5f98dc4c29824b4c>`__)
+-  **auto-discover:** add plugins, setuptools way
+   (`10794a94 <https://github.com/abravalheri/pyangext/commit/10794a9412fbbda6f88ee8d4069960efd09bcffa>`__)
+-  **ctx:** add utility function to context creation
+   (`72f43d90 <https://github.com/abravalheri/pyangext/commit/72f43d9012a61dc665626e613d45dbbd6d036807>`__)
+-  **parse:** add parse function (str => AST)
+   (`ab3b465b <https://github.com/abravalheri/pyangext/commit/ab3b465bd29bd334ca126f5a4b2ff39968a31948>`__)
+
+Documentation
+-------------
+
+-  improve doc generation and contents
+   (`e471c595 <https://github.com/abravalheri/pyangext/commit/e471c59593de288df9abbf4fd6196d20323d7b27>`__)
+-  **create\_context:** document options for context
+   (`c2ad6d0f <https://github.com/abravalheri/pyangext/commit/c2ad6d0fa006c801c4bdcb8bfa676effd3741d53>`__)
+-  **project:** improve overall project docs.
+   (`e1b60ecd <https://github.com/abravalheri/pyangext/commit/e1b60ecdf6df06bf30b11c19b75954356bad505f>`__)
+-  **requirements:** create a separated req file
+   (`94882cd4 <https://github.com/abravalheri/pyangext/commit/94882cd41452e7892fa977ff846f72fea8cba4bc>`__)
+
+Test
+----
+
+-  **cli:** Add cli tests
+   (`11501c44 <https://github.com/abravalheri/pyangext/commit/11501c443bbfecc4f328466baea18f163ca95060>`__)

CONTRIBUTING.rst

@@ -25,7 +25,7 @@ a better person).
 Please, try to keep your commit messages as communicative as possible.
 There is a good
 `reference <https://github.com/erlang/otp/wiki/Writing-good-commit-messages>`_
-for it as well :blush:.
+for it as well.
 
 .. note::
     I usually think in the commit itself as an implicit subject of
@@ -85,7 +85,7 @@ Reporting a Bug
 -  If possible, submit a Pull Request with a failing test. It would be
    wonderful to increase the test coverage!
 -  Consider the challenge of fixing the bug, I'm sure it can be funny or
-   at least very aggrandizing :stuck_out_tongue_winking_eye:
+   at least very aggrandizing.
 
 Requesting a Feature
 --------------------
@@ -106,14 +106,12 @@ Requesting a Feature
    code. We always have more work to do than time to do it. If you can
    write some code then that will speed the process along.
 
-NOTE
-----
-
-This guide was partially copied from
+.. note::
+    This guide was partially copied from
 
-- `ember.js <https://raw.githubusercontent.com/emberjs/ember.js/master/CONTRIBUTING.md>`_
-- `factory_girl <https://raw.github.com/thoughtbot/factory_girl_rails/master/CONTRIBUTING.md>`_
-- `puppet <https://raw.githubusercontent.com/puppetlabs/puppet/master/CONTRIBUTING.md>`_
-- `rails <http://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html#contributing-to-the-rails-documentation>`_
+    - `ember.js <https://raw.githubusercontent.com/emberjs/ember.js/master/CONTRIBUTING.md>`_
+    - `factory_girl <https://raw.github.com/thoughtbot/factory_girl_rails/master/CONTRIBUTING.md>`_
+    - `puppet <https://raw.githubusercontent.com/puppetlabs/puppet/master/CONTRIBUTING.md>`_
+    - `rails <http://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html#contributing-to-the-rails-documentation>`_
 
-Please consider reading them. They are just great!
+    Please consider reading them. They are just great!

README.rst

@@ -171,4 +171,4 @@ Ultimate Goals
 .. |setuptools| replace:: ``setuptools``
 .. _setuptools: https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins
 .. |guidelines| replace:: Contribution Guidelines
-.. _guidelines: https://github.com/abravalheri/pyangext/blob/master/CONTRIBUTING.rst
+.. _guidelines: http://pyangext.readthedocs.io/en/latest/contributing.html

doc-requirements.txt

@@ -1,7 +1,4 @@
-click
-git+https://github.com/abravalheri/pyang.git@deploy#egg=pyang
-inflection
+-r requirements.txt
 pyenchant
-six
 sphinx_rtd_theme
 sphinxcontrib-spelling

pyangext/cli.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-"""Command line tools for pyang + sensible extensions.
+"""Extension for the pyang command line interface.
 
 This module includes tools for augmenting ``PYANG_PLUGINPATH`` with
 the location of auto-discovered pyang plugins.
@@ -16,7 +16,8 @@
 In this sense, ``pyangext run`` command can be used as a bridge to
 the ``pyang`` command, but using the auto-discovery feature.
 
-.. note:: Including non pyang-plugin python files alongside pyang-plugins
+Note:
+    Including non pyang-plugin python files alongside pyang-plugins
     python files (in the same directory) will result in a pyang CLI crash.
 
     It is recommended that the function registered as entry-point follows
@@ -26,7 +27,7 @@
     - it should call ``pyang.plugin.register_plugin`` with an instance of
       ``pyang.plugin.PyangPlugin`` as argument.
 
-.. seealso::
+See Also:
     https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins
 
 
@@ -82,12 +83,11 @@
 
 
 def _fixdoc(func):
-    """Fix the text wrapping in a function's docstring"""
+    """Return a new text with the text wrapping in a function's docstring"""
     docstring = dedent(func.__doc__)
     lines = (' '.join(line.split()) for line in docstring.split('\n\n'))
 
     new_docstring = "\n".join(lines)
-    func.__doc__ = new_docstring
 
     return new_docstring
 
@@ -116,7 +116,9 @@ def export_path(ctx, _, value):
     environment variable.
 
     Example:
-        eval $(pyangext --export-path)
+        ::
+
+            eval $(pyangext --export-path)
     """
     if not value or ctx.resilient_parsing:
         return
@@ -137,27 +139,20 @@ def export_path(ctx, _, value):
     '--init', '--export-path', help=_fixdoc(export_path),
     is_flag=True, expose_value=False, callback=export_path)
 def call():
-    """\
-    pyang + sensible extensions
+    """pyang + sensible extensions
 
     Includes self-registered pyang plugin auto-discovery
     """
     pass
 
-_fixdoc(call)
-
 
 @call.command(
     'run', context_settings={'ignore_unknown_options': True})
 @click.argument('args', nargs=-1, type=click.UNPROCESSED)
 def call_pyang(args):
-    """\
-    invoke pyang script with plugin path adjusted using auto-discovery
-    """
+    """invoke pyang script with plugin path adjusted using auto-discovery."""
 
     environ['PYANG_PLUGINPATH'] = pathsep.join(expanded())
     proc = Popen(['pyang'] + list(args), stdout=sys.stdout, stderr=sys.stderr)
     proc.wait()
     return proc.returncode
-
-_fixdoc(call_pyang)

pyangext/definitions.py

@@ -1,11 +1,16 @@
 # -*- coding: utf-8 -*-
-"""Meta information about YANG modeling language."""
+"""Meta information about YANG modeling language.
+
+See also:
+    https://tools.ietf.org/html/rfc6020
+"""
 
 __author__ = "Anderson Bravalheri"
 __copyright__ = "Copyright (C) 2016 Anderson Bravalheri"
 __license__ = "mozilla"
 
 PREFIX_SEPARATOR = ':'
+"""Character used to denote prefix in YANG language."""
 
 URL_SEPARATOR = '/'
 
@@ -30,6 +35,7 @@
     'uint8',
     'union',
 ]
+"""Types supported by default in the YANG language."""
 
 YANG_KEYWORDS = [
     'action',
@@ -101,18 +107,21 @@
     'yang-version',
     'yin-element',
 ]
+"""YANG language Keywords."""
 
 HEADER_STATEMENTS = [
     'organization',
     'contact',
     'revision',
     'yang-version',
 ]
+"""Descriptive statements used in the header of a module or submodule."""
 
 ID_STATEMENTS = [
     'namespace',
     'prefix',
 ]
+"""Statements used to identify the module."""
 
 DATA_STATEMENTS = [
     'container',
@@ -121,3 +130,4 @@
     'list',
     'anyxml',
 ]
+"""Statements that denote a data node in the abstract tree."""

pyangext/utils.py

@@ -230,7 +230,8 @@ def select(statements, keyword=None, arg=None, ignore_prefix=False):
 def find(parent, keyword=None, arg=None, ignore_prefix=False):
     """Select all sub-statements by keyword, or argument or both.
 
-    .. seealso:: function :func:`select`
+    See Also:
+        function :func:`select`
     """
     return select(parent.substmts, keyword, arg, ignore_prefix)
 
@@ -371,7 +372,7 @@ def parse(text, ctx=None):
     Returns:
         pyang.statements.Statement: Abstract syntax subtree
 
-    Notes:
+    Note:
         The ``parse`` function can be used to parse small amounts of text.
         If yout plan to parse an entire YANG (sub)module, please use instead::
 

requirements.txt

@@ -1,4 +1,4 @@
 click
-git+https://github.com/abravalheri/pyang.git@deploy#egg=pyang
 inflection
+pyang
 six