diff --git a/docs/code.rst b/docs/code.rst deleted file mode 100644 index 8271b60..0000000 --- a/docs/code.rst +++ /dev/null @@ -1,5 +0,0 @@ - -Code -==== - -To do: This part of the documentation will cover all the code of Stilus. diff --git a/docs/code/cli.rst b/docs/code/cli.rst new file mode 100644 index 0000000..f096e8a --- /dev/null +++ b/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 diff --git a/docs/code/lexer_and_parser.rst b/docs/code/lexer_and_parser.rst new file mode 100644 index 0000000..abee27a --- /dev/null +++ b/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: diff --git a/docs/code/nodes.rst b/docs/code/nodes.rst new file mode 100644 index 0000000..67ed853 --- /dev/null +++ b/docs/code/nodes.rst @@ -0,0 +1,5 @@ + +Nodes +===== + +The modes go here. diff --git a/docs/code/visitors.rst b/docs/code/visitors.rst new file mode 100644 index 0000000..391e0f0 --- /dev/null +++ b/docs/code/visitors.rst @@ -0,0 +1,5 @@ + +Visitors +======== + +The visitors go here. diff --git a/docs/conf.py b/docs/conf.py index 235cb1d..a93931b 100644 --- a/docs/conf.py +++ b/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 ----------------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index c60b263..6957ba4 100644 --- a/docs/index.rst +++ b/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 `_ + are missing. + +Below you'll find the comparison between Stylus and Stilus. + +.. toctree:: + :maxdepth: 1 + + The Stylus binary + The Stylus test cases 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 ================== diff --git a/docs/plan/current.md b/docs/plan/current.md index 37728c8..ac90433 100644 --- a/docs/plan/current.md +++ b/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. diff --git a/poetry.lock b/poetry.lock index 52b6198..9f12a95 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1028,7 +1028,7 @@ docs = ["sphinx", "jaraco.packaging (>=3.2)", "rst.linker (>=1.9)"] testing = ["pathlib2", "contextlib2", "unittest2"] [metadata] -content-hash = "c00a628642b2c5d9580f28891dcb9716db7a69c0f8f80dc91fa9e04257e7aff3" +content-hash = "75280d43b91fffef0e8bcf318bf55ec9f175dbf8babaf59f0eabd817a25582cd" python-versions = "^3.6" [metadata.files] diff --git a/pyproject.toml b/pyproject.toml index f0dd029..f10b7ab 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -40,7 +40,7 @@ twine = "*" pytest-runner = "*" "flake8" = "*" pytest-cov = "*" -sphinx = "*" +sphinx = "^2.3.1" codecov = "*" recommonmark = "*" commonmark = "*" diff --git a/stilus/cli.py b/stilus/cli.py index 7cc9442..92753b3 100644 --- a/stilus/cli.py +++ b/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): diff --git a/stilus/lexer.py b/stilus/lexer.py index 24bebad..cf2a021 100644 --- a/stilus/lexer.py +++ b/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): diff --git a/stilus/parser.py b/stilus/parser.py index dc81c20..eb067cf 100644 --- a/stilus/parser.py +++ b/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: