__main__.py

__main__.py

# -*- coding: utf-8 -*-

"""
This module provides a script to document Radish step implementations
"""

from sys import exit

from os.path import split

from docopt import docopt

from radish import __VERSION__

from radish.documentors.sphinx.multipage import MultiPageSphinxDocumentSet
from radish.documentors.sphinx.singlepage import SinglePageSphinxDocument
from radish.documentors.steps_writer import StepsDocumentWriter

from radish.errororacle import error_oracle, enable_excepthook

from radish.exceptions import RadishError

from radish.loader import load_module_assets

from radish.main import setup_config

from radish.stepregistry import StepRegistry


# ........................................................................... #
@error_oracle
def main():
    usage = """
Usage:
    radish-docs sphinx <module-path>
        [-o=<folder-path> | --output-folder=<folder-path>]
        [--index-file-name=<file-path> ]
        [-s=<file-path> | --single-file=<file-path>]
        [-c | --print-to-console]
        [--label-prefix=<label-prefix>]
        [-r | --recreate]
        [--no-ansi]
    radish-docs (-h | --help)
    radish-docs (-v | --version)

Commands:
    sphinx
      create Sphinx documentation

Arguments:
    modules-path
      path to python step modules to document

Options:
    -o=<folder-path>, --output-folder=<folder-path>   location of the output folder,
                                                      by default `_build` in the current working folder

    --index-file-name=<file-name>                     optional, name for the index file created by `--output-folder`,
                                                      by default "index.rst". This file is placed in the output folder.

    -s=<file-path>, --single-file=<file-path>         write documentation to a single file

    -c, --print-to-console
      print `--single-file` documentaiton to console

    --label-prefix=<label-prefix>
      label prefix used for various section of the generated docs. Can be used
      if you need a unique on in your documentation. By default set to
      `radish.document_id.`

    -r, --recreate
      recreate output folder or file by removing and creating it again.

    -h, --help
      show this screen

    -v, --version
      show version

(C) Copyright by Timo Furrer <[email protected]>
    """

    # enable errororacles except hook system wide
    enable_excepthook()

    # parse sys.argv against our docopt argments
    arguments = docopt("radish-docs {0}\n{1}".format(__VERSION__, usage),
                       version=__VERSION__)

    # create world wide configuration
    setup_config(arguments)

    # process arguments for "sphinx" command
    if arguments['sphinx']:
        # get the module path
        module_path = arguments['<module-path>']

        # get the output folder or if missing set the default for the
        # output_folder_path
        if arguments['--output-folder'] is not None:
            output_folder_path = arguments['--output-folder']
        else:
            output_folder_path = "${PWD}/_build"

        # get the index file name, otherwise default it to index.rst
        if arguments['--index-file-name'] is not None:
            index_file_name = arguments['--index-file-name']
            # test if given file name rather then path, raises RadishError
            _test_file_name(index_file_name, '--index-file-name')
        else:
            index_file_name = "index.rst"

        # set recreate file
        single_file_path = arguments['--single-file']
        # set print to console flag
        print_to_console = arguments['--print-to-console']

        # if console is specified then then set single file to none and
        # output_folder_path to None, recreate to Flase
        if print_to_console is True:
            single_file_path = None
            output_folder_path = None
            recreate = False

        # set label prefix
        if arguments['--label-prefix'] is not None:
            label_prefix = arguments['--label-prefix']
        else:
            label_prefix = "radish.document_id."

        # set recreate flag
        recreate = arguments['--recreate']

        return_code = document_with_sphinx(module_path,
                                           output_folder_path,
                                           index_file_name,
                                           single_file_path,
                                           recreate,
                                           print_to_console,
                                           label_prefix)
        return return_code


# ........................................................................... #
def document_with_sphinx(module_path, output_folder_path=None,
                         index_file_name="index.rst", single_file_path=None,
                         recreate=False, print_to_console=False,
                         label_prefix="radish.document_id."):

    # load the module
    load_module_assets(module_path)

    # get the steps which will be documented
    steps = StepRegistry().steps

    # write documentation to the sphinx document object
    steps_writer = StepsDocumentWriter(steps=steps, basedir=module_path)

    # if there is no output folder and single file is specified then
    # output to console
    if print_to_console is True:
        # for console we default the index file path to radish.rst since
        # it really does not matter what it is
        document_set = SinglePageSphinxDocument(label_prefix=label_prefix,
                                                index_file_path="radish.rst")
        # write steps documentation to the documentset
        steps_writer.write_to(document_set)
        # print document set to console
        document_set.print_to_console()
    elif single_file_path is not None:

        # create single page sphinx document, which is actually set of document
        # sections
        # get the filename only
        single_file_name = split(single_file_path)[1]
        document_set = SinglePageSphinxDocument(
            label_prefix=label_prefix,
            index_file_path=single_file_name)
        # write steps documentation to the documentset
        steps_writer.write_to(document_set)
        # write generated documentation to a file
        document_set.write_file(single_file_path, recreate)
    else:
        # index_file_name is our index_file_path since all the paths are
        # relative to the output_folder
        document_set = MultiPageSphinxDocumentSet(
            label_prefix=label_prefix,
            index_file_path=index_file_name)
        # write steps documentation to the documentset
        steps_writer.write_to(document_set)
        # write generated documentation to a files
        document_set.write_files(output_folder_path, recreate)

    # for now always return 0, error oracle will take care of other error codes
    return 0


# ........................................................................... #
def _test_file_name(file_name, command_line_option):
    if split(file_name) != ('', file_name):
        msg = "%s value should be a file name not a file path: %s" % \
            (command_line_option, command_line_option)
        raise RadishError(msg)


# ........................................................................... #
if __name__ == "__main__":
    exit(main())