Merge pull request #44 from jw/#43_docstrings

#43 docstrings

docs/code/cli.rst

@@ -0,0 +1,18 @@
+
+Stilus
+======
+
+.. module:: stilus.cli
+
+This part of the documentation covers the Stilus binary.
+
+The main function
+-----------------
+
+.. autofunction:: stilus
+
+Some helper functions
+---------------------
+
+.. autofunction:: prepare_watch
+.. autofunction:: print_version

docs/code/lexer_and_parser.rst

@@ -0,0 +1,27 @@
+
+Token, Lexer and Parser
+=======================
+
+Token
+-----
+
+.. autoclass:: stilus.lexer.Token
+   :members:
+   :private-members:
+   :special-members:
+
+Lexer
+-----
+
+.. autoclass:: stilus.lexer.Lexer
+   :members:
+   :private-members:
+   :special-members:
+
+Parser
+------
+
+.. autoclass:: stilus.parser.Parser
+   :members:
+   :private-members:
+   :special-members:

docs/code/nodes.rst

@@ -0,0 +1,5 @@
+
+Nodes
+=====
+
+The modes go here.

docs/code/visitors.rst

@@ -0,0 +1,5 @@
+
+Visitors
+========
+
+The visitors go here.

docs/conf.py

@@ -16,12 +16,10 @@
 import os  # noqa
 import sys  # noqa
 
-sys.path.insert(0, os.path.abspath('../stilus'))
-
-from stilus.lexer import Lexer  # noqa
-from stilus.parser import Parser  # noqa
-from __version__ import __version__  # noqa
+sys.path.insert(0, os.path.abspath('..'))
 
+import stilus  # noqa
+from stilus.__version__ import __version__  # noqa
 import recommonmark  # noqa
 
 # -- Project information -----------------------------------------------------

docs/index.rst

@@ -36,7 +36,7 @@ Install Stilus on your machine using pip:
  $ python -m pip install -U stilus
  $ pip install -U stilus
 
-It might be that you'll need to install some extra dev packages. This might help:
+It might be that you'll need to install some extra dev packages. Like this:
 
 .. code-block:: bash
 
@@ -62,24 +62,26 @@ Stilus
    -V, --version       Display the version of Stilus.
    -h, --help          Show this message and exit.
 
-In progress...
---------------
-
-.. toctree::
-   :maxdepth: 1
-
-   diff/stilus.md
-   diff/tests.rst
-
-The Missing Parts
------------------
+Comparison between Stylus and Stilus
+------------------------------------
 
 Most of Stylus is implemented in Stilus, but some parts are missing:
 
  - Plugins
  - Caching
- - Documentation: missing an architecture and docstring data
- - Missing some tests (+95% of the Stylus tests pass through Stilus)
+ - Documentation: missing an architecture document and almost all the docstrings
+ - We are missing a few tests.  Currently more than 95% of the Stylus tests
+   pass successfully through Stilus.
+   `These <https://github.com/jw/stilus/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Atest>`_
+   are missing.
+
+Below you'll find the comparison between Stylus and Stilus.
+
+.. toctree::
+   :maxdepth: 1
+
+   The Stylus binary <diff/stilus.md>
+   The Stylus test cases <diff/tests.rst>
 
 All help is appreciated!
 
@@ -128,12 +130,15 @@ Code
 ----
 
 If you are looking for information on a specific function, class, or method,
-this part of the documentation is for you.  (c) requests ;-)
+this part of the documentation is for you.
 
 .. toctree::
    :maxdepth: 1
 
-   code.rst
+   code/lexer_and_parser.rst
+   code/nodes.rst
+   code/cli.rst
+   code/visitors.rst
 
 Indices and tables
 ==================

docs/plan/current.md

@@ -6,6 +6,6 @@ The issues release, a.k.a. `issues, issues everywhere!`
  - [x] Migrate from pipenv to poetry.
  - [ ] Start using black.
  - [ ] Cleanup of coverall/codecov properties.
- - [ ] Document using docstrings and Sphinx.
+ - [x] Document using docstrings and Sphinx.
  - [x] Start using github issues.
- - [ ] Clear all the issues with a 'test' label.]\
+ - [ ] Clear all the issues with a 'test' label.

pyproject.toml

@@ -40,7 +40,7 @@ twine = "*"
 pytest-runner = "*"
 "flake8" = "*"
 pytest-cov = "*"
-sphinx = "*"
+sphinx = "^2.3.1"
 codecov = "*"
 recommonmark = "*"
 commonmark = "*"

stilus/cli.py

@@ -46,6 +46,13 @@ def setup_logging(default_path='logging.yaml',
 
 
 def print_version(ctx, param, value):
+    """
+    Print the version of Stilus and end the process.
+
+    :param ctx: The click context.
+    :param param: A parameter.
+    :param value: A value
+    """
     if not value or ctx.resilient_parsing:
         return
     click.echo(f'{__version__}')
@@ -57,6 +64,7 @@ def validate_path(ctx, param, value):
 
 
 def fail(message, prefix=None, code=-1):
+    """Show a message and end the process."""
     if not prefix:
         prefix = '     error '
     click.echo(click.style(prefix, fg='red'), nl=False)
@@ -65,6 +73,7 @@ def fail(message, prefix=None, code=-1):
 
 
 def fancy_output(message, prefix=None):
+    """"""
     if prefix:
         click.echo(click.style(prefix, dim=True), nl=False)
     click.echo(message)
@@ -145,13 +154,14 @@ def prepare_watch(path: Path,
     """
     Compile all Stylus files in the given path and recompile
     automatically when these files change.
+
     :param path: A path.
     :type path: Path
     :param includes: List of directories to include.
     :type includes: list, optional
     :param compress: Compress the output?  False by default.
     :type compress: bool, optional
-    :param prefix: Prefix to add to each css class..
+    :param prefix: Prefix to add to each css class.
     :type prefix: Str, optional
     :param ha: Hoist atrules?  False by default.
     :type ha: bool, optional
@@ -172,7 +182,7 @@ def prepare_watch(path: Path,
 def check_out(out: str) -> None:
     """
     Check of the given out str is an existing directory.  Otherwise
-    fiail
+    fail.
     :param out: A possibly existing directory
     :type out: str
     """
@@ -204,6 +214,22 @@ def check_out(out: str) -> None:
               help='Display the version of Stilus.')
 def stilus(verbose, watch, compress, print_, include, out, input, output,
            prefix, ha):
+    """
+    The Stilus binary.
+
+    :param verbose: More verbose output.
+    :param watch: Compile all styl files in a directory and watch that
+                  directory for changes.
+    :param compress: Compress the resuting css.
+    :param print_: Print the output to stdout.
+    :param include:
+    :param out:
+    :param input:
+    :param output:
+    :param prefix:
+    :param ha:
+    :return:
+    """
 
     class StilusHandler(FileSystemEventHandler):
         def on_modified(self, event):

stilus/lexer.py

@@ -14,6 +14,7 @@
 class Token:
 
     def __init__(self, type, value=None, space=None, lineno=None, column=None):
+        """A token."""
         self.type = type
         self.value = value
         self.space = space
@@ -22,12 +23,14 @@ def __init__(self, type, value=None, space=None, lineno=None, column=None):
         self.column = column
 
     def __str__(self):
+        """Return the value if available, the tokens type otherwise."""
         if self.value:
             return f'{self.value}'
         else:
             return f'{self.type}'
 
     def __repr__(self):
+        """Return the value if available, the tokens type otherwise."""
         return str(self)
 
     def __key(self):

stilus/parser.py

@@ -193,6 +193,12 @@ def previous_state(self):
             raise e
 
     def parse(self) -> Node:
+        """
+        Parse the given source string.
+
+        :return: The root Node.
+        :rtype: Node
+        """
         block = self.parent = self.root
         while 'eos' != self.peek().type:
             self.skip_whitespace()
@@ -293,7 +299,7 @@ def line_contains(self, type):
             la = self.lookahead(i)
 
     def selector_token(self):
-        """Valid selector tokens"""
+        """Valid selector tokens."""
         if self.is_selector_token(1):
             if '{' == self.peek().type: