From 8e9640cd384c6c5b36ea480403c07d1532eaf4c2 Mon Sep 17 00:00:00 2001 From: Anthony Scopatz Date: Fri, 23 Jun 2017 12:02:05 -0400 Subject: [PATCH] started docs --- CHANGELOG.rst | 6 + CONTRIBUTING.rst | 286 ++++++++++++++++++++ docs/Makefile | 130 +++++++++ docs/_static/numpy_friendly.css_t | 5 + docs/_templates_overwrite/layout.html | 6 + docs/api/blank.rst | 11 + docs/api/environ.rst | 10 + docs/api/index.rst | 15 ++ docs/api/main.rst | 10 + docs/changelog.rst | 1 + docs/conf.py | 306 +++++++++++++++++++++ docs/dependencies.rst | 28 ++ docs/devguide.rst | 1 + docs/envvars.rst | 7 + docs/index.rst | 367 ++++++++++++++++++++++++++ news/TEMPLATE.rst | 11 + 16 files changed, 1200 insertions(+) create mode 100644 CHANGELOG.rst create mode 100644 CONTRIBUTING.rst create mode 100644 docs/Makefile create mode 100644 docs/_static/numpy_friendly.css_t create mode 100644 docs/_templates_overwrite/layout.html create mode 100644 docs/api/blank.rst create mode 100644 docs/api/environ.rst create mode 100644 docs/api/index.rst create mode 100644 docs/api/main.rst create mode 100644 docs/changelog.rst create mode 100644 docs/conf.py create mode 100644 docs/dependencies.rst create mode 120000 docs/devguide.rst create mode 100644 docs/envvars.rst create mode 100644 docs/index.rst create mode 100644 news/TEMPLATE.rst diff --git a/CHANGELOG.rst b/CHANGELOG.rst new file mode 100644 index 0000000..9779c14 --- /dev/null +++ b/CHANGELOG.rst @@ -0,0 +1,6 @@ +==================== +Rever Change Log +==================== + +.. current developments + diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000..1eb9c85 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,286 @@ +.. _devguide: + +================= +Developer's Guide +================= +Welcome to the rever developer's guide! This is a place for developers to +place information that does not belong in the user's guide or the library +reference but is useful or necessary for the next people that come along to +develop rever. + +.. note:: All code changes must go through the pull request review procedure. + + +Changelog +========= +Pull requests will often have CHANGELOG entries associated with. However, +to avoid excessive merge conflicts, please follow the following procedure: + +1. Go into the ``news/`` directory, +2. Copy the ``TEMPLATE.rst`` file to another file in the ``news/`` directory. + We suggest using the branchname:: + + $ cp TEMPLATE.rst branch.rst + +3. Add your entries as a bullet pointed lists in your ``branch.rst`` file in + the appropriate category. It is OK to leave the ``None`` entries for later + use. +4. Commit your ``branch.rst``. + +Feel free to update this file whenever you want! Please don't use someone +else's file name. All of the files in this ``news/`` directory will be merged +automatically at release time. The ``None`` entries will be automatically +filtered out too! + + +Style Guide +=========== +rever is a pure Python project, and so we use PEP8 (with some additions) to +ensure consistency throughout the code base. + +---------------------------------- +Rules to Write By +---------------------------------- +It is important to refer to things and concepts by their most specific name. +When writing rever code or documentation please use technical terms +appropriately. The following rules help provide needed clarity. + +********** +Interfaces +********** +* User-facing APIs should be as generic and robust as possible. +* Tests belong in the top-level ``tests`` directory. +* Documentation belongs in the top-level ``docs`` directory. + +************ +Expectations +************ +* Code must have associated tests and adequate documentation. +* User-interaction code (such as the Shell class) is hard to test. + Mechanism to test such constructs should be developed over time. +* Have *extreme* empathy for your users. +* Be selfish. Since you will be writing tests you will be your first user. + +------------------- +Python Style Guide +------------------- +rever uses `PEP8`_ for all Python code. The following rules apply where `PEP8`_ +is open to interpretation. + +* Use absolute imports (``import rever.tools``) rather than explicit + relative imports (``import .tools``). Implicit relative imports + (``import tools``) are never allowed. +* Use ``'single quotes'`` for string literals, and + ``"""triple double quotes"""`` for docstrings. Double quotes are allowed to + prevent single quote escaping, e.g. ``"Y'all c'mon o'er here!"`` +* We use sphinx with the numpydoc extension to autogenerate API documentation. Follow + the `numpydoc`_ standard for docstrings. +* Simple functions should have simple docstrings. +* Lines should be at most 80 characters long. The 72 and 79 character + recommendations from PEP8 are not required here. +* All Python code should be compliant with Python 3.4+. At some + unforeseen date in the future, Python 2.7 support *may* be supported. +* Tests should be written with pytest using a procedural style. Do not use + unittest directly or write tests in an object-oriented style. +* Test generators make more dots and the dots must flow! + +You can easily check for style issues, including some outright bugs such +as mispelled variable names, using pylint. If you're using Anaconda you'll +need to run "conda install pylint" once. You can easily run pylint on +the edited files in your uncommited git change:: + + $ pylint $(git status -s | awk '/\.py$$/ { print $$2 }' | sort) + +If you want to lint the entire code base run:: + + $ pylint $(find tests rever -name \*.py | sort) + + +How to Test +================ + +---------------------------------- +Dependencies +---------------------------------- + +Prep your environment for running the tests:: + + $ pip install -r requirements-tests.txt + + +---------------------------------- +Running the Tests - Basic +---------------------------------- + +Run all the tests using pytest:: + + $ py.test -q + +Use "-q" to keep pytest from outputting a bunch of info for every test. + +---------------------------------- +Running the Tests - Advanced +---------------------------------- + +To perform all unit tests:: + + $ py.test + +If you want to run specific tests you can specify the test names to +execute. For example to run test_aliases:: + + $ py.test test_aliases.py + +Note that you can pass multiple test names in the above examples:: + + $ py.test test_aliases.py test_environ.py + +---------------------------------- +Writing the Tests - Advanced +---------------------------------- + +(refer to pytest documentation) + +With the Pytest framework you can use bare `assert` statements on +anything you're trying to test, note that the name of the test function +has to be prefixed with `test_`:: + + def test_whatever(): + assert is_true_or_false + +The conftest.py in tests directory defines fixtures for mocking various +parts of rever for more test isolation. For a list of the various fixtures:: + + $ py.test --fixtures + +when writing tests it's best to use pytest features i.e parametrization:: + + @pytest.mark.parametrize('env', [test_env1, test_env2]) + def test_one(env, rever_builtins): + rever_builtins.__rever_env__ = env + ... + +this will run the test two times each time with the respective `test_env`. +This can be done with a for loop too but the test will run +only once for the different test cases and you get less isolation. + +With that in mind, each test should have the least `assert` statements, +preferably one. + +At the moment, rever doesn't support any pytest plugins. + +Happy Testing! + + +How to Document +==================== +Documentation takes many forms. This will guide you through the steps of +successful documentation. + +---------- +Docstrings +---------- +No matter what language you are writing in, you should always have +documentation strings along with you code. This is so important that it is +part of the style guide. When writing in Python, your docstrings should be +in reStructured Text using the `numpydoc`_ format. + +------------------------ +Auto-Documentation Hooks +------------------------ +The docstrings that you have written will automatically be connected to the +website, once the appropriate hooks have been setup. At this stage, all +documentation lives within rever's top-level ``docs`` directory. +We uses the sphinx tool to manage and generate the documentation, which +you can learn about from `the sphinx website `_. +If you want to generate the documentation, first rever itself must be installed +and then you may run the following command from the ``docs`` dir: + +.. code-block:: console + + ~/rever/docs $ make html + +For each new +module, you will have to supply the appropriate hooks. This should be done the +first time that the module appears in a pull request. From here, call the +new module ``mymod``. The following explains how to add hooks. + +------------------------ +Python Hooks +------------------------ +Python documentation lives in the ``docs/api`` directory. +First, create a file in this directory that represents the new module called +``mymod.rst``. +The ``docs/api`` directory matches the structure of the ``rever/`` directory. +So if your module is in a sub-package, you'll need to go into the sub-package's +directory before creating ``mymod.rst``. +The contents of this file should be as follows: + +**mymod.rst:** + +.. code-block:: rst + + .. _rever_mymod: + + ======================================= + My Awesome Module -- :mod:`rever.mymod` + ======================================= + + .. currentmodule:: rever.mymod + + .. automodule:: rever.mymod + :members: + +This will discover all of the docstrings in ``mymod`` and create the +appropriate webpage. Now, you need to hook this page up to the rest of the +website. + +Go into the ``index.rst`` file in ``docs/rever`` or other subdirectory and add +``mymod`` to the appropriate ``toctree`` (which stands for table-of-contents +tree). Note that every sub-package has its own ``index.rst`` file. + + +Building the Website +=========================== + +Building the website/documentation requires the following dependencies: + +#. `Sphinx `_ +#. `Cloud Sphinx Theme `_ + +----------------------------------- +Procedure for modifying the website +----------------------------------- +The rever website source files are located in the ``docs`` directory. +A developer first makes necessary changes, then rebuilds the website locally +by executing the command:: + + $ make html + +This will generate html files for the website in the ``_build/html/`` folder. +The developer may view the local changes by opening these files with their +favorite browser, e.g.:: + + $ google-chrome _build/html/index.html + +Once the developer is satisfied with the changes, the changes should be +committed and pull-requested per usual. Once the pull request is accepted, the +developer can push their local changes directly to the website by:: + + $ make push-root + +Branches and Releases +============================= +Mainline rever development occurs on the ``master`` branch. Other branches +may be used for feature development (topical branches) or to represent +past and upcoming releases. + + +Document History +=================== +Portions of this page have been forked from the PyNE and Xonsh documentation, +Copyright 2015-2016, the xonsh developers. All rights reserved. +Copyright 2011-2015, the PyNE Development Team. All rights reserved. + +.. _PEP8: https://www.python.org/dev/peps/pep-0008/ +.. _numpydoc: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..45a7cad --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,130 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build +RELEASE = v0.1 + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +DOCREPONAME = xonsh-docs +DOCREPOURL = git@github.com:scopatz/xonsh-docs.git +DOCREPOBRANCH = gh-pages + +.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/metasci.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/metasci.qhc" + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +push-latest: + cd $(BUILDDIR) && \ + test -d $(DOCREPONAME) || git clone $(DOCREPOURL) $(DOCREPONAME) && \ + cd $(DOCREPONAME) && \ + git pull origin $(DOCREPOBRANCH) && \ + test -d latest || mkdir latest && touch latest/_ && \ + rm -r latest/* && \ + cp -r ../html/* latest/ && \ + git add latest/ && \ + git commit -am "Pushed latest docs at $(date)" && \ + git push + +push-release: + cd $(BUILDDIR) && \ + test -d $(DOCREPONAME) || git clone $(DOCREPOURL) $(DOCREPONAME) && \ + cd $(DOCREPONAME) && \ + git pull origin $(DOCREPOBRANCH) && \ + test -d $(RELEASE) || mkdir $(RELEASE) && touch $(RELEASE)/_ && \ + rm -r $(RELEASE)/* && \ + cp -r ../html/* $(RELEASE)/ && \ + git add $(RELEASE)/ && \ + git commit -am "Pushed $(RELEASE) docs at $(date)" && \ + git push + +push-root: + cd $(BUILDDIR) && \ + test -d $(DOCREPONAME) || git clone $(DOCREPOURL) $(DOCREPONAME) && \ + cd $(DOCREPONAME) && \ + git pull origin $(DOCREPOBRANCH) && \ + rm -rf api previous _sources _static *.html *.js *.inv && \ + cp -r ../html/* . && \ + git add . && \ + git commit -am "Pushed root-level docs at $(date)" && \ + git push + diff --git a/docs/_static/numpy_friendly.css_t b/docs/_static/numpy_friendly.css_t new file mode 100644 index 0000000..2ca4601 --- /dev/null +++ b/docs/_static/numpy_friendly.css_t @@ -0,0 +1,5 @@ +@import url("cloud.css"); + +table.docutils th.field-name { + white-space: nowrap; +} diff --git a/docs/_templates_overwrite/layout.html b/docs/_templates_overwrite/layout.html new file mode 100644 index 0000000..1eb065d --- /dev/null +++ b/docs/_templates_overwrite/layout.html @@ -0,0 +1,6 @@ +{% extends '!layout.html' %} + +{% block extrahead %} + {{ super() }} + +{% endblock %} diff --git a/docs/api/blank.rst b/docs/api/blank.rst new file mode 100644 index 0000000..62b4e94 --- /dev/null +++ b/docs/api/blank.rst @@ -0,0 +1,11 @@ +.. _rever_mod: + +******************************************************************************** + (``rever.mod``) +******************************************************************************** + +.. automodule:: rever.mod + :members: + :undoc-members: + :inherited-members: + diff --git a/docs/api/environ.rst b/docs/api/environ.rst new file mode 100644 index 0000000..4f234a8 --- /dev/null +++ b/docs/api/environ.rst @@ -0,0 +1,10 @@ +.. _rever_environ: + +****************************************************** +Environment (``rever.environ``) +****************************************************** + +.. automodule:: rever.environ + :members: + :undoc-members: + :inherited-members: diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 0000000..24f899f --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,15 @@ +.. _api: + +================= +Rever API +================= +For those of you who want the gritty details. + + +**Helpers:** + +.. toctree:: + :maxdepth: 1 + + environ + main diff --git a/docs/api/main.rst b/docs/api/main.rst new file mode 100644 index 0000000..7bf0855 --- /dev/null +++ b/docs/api/main.rst @@ -0,0 +1,10 @@ +.. _rever_main: + +****************************************************** +Command Line Interface (``rever.main``) +****************************************************** + +.. automodule:: rever.main + :members: + :undoc-members: + :inherited-members: diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 0000000..4d7817a --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1 @@ +.. include:: ../CHANGELOG.rst \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..28a037f --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,306 @@ +# -*- coding: utf-8 -*- +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. +import os +import sys +import builtins +import inspect +import importlib + +os.environ['XONSH_DEBUG'] = '1' + +from xonsh.environ import DEFAULT_DOCS, Env +from xonsh.xontribs import xontrib_metadata +from xonsh import main +from xonsh.commands_cache import CommandsCache + +spec = importlib.util.find_spec('prompt_toolkit') +if spec is not None: + # hacky runaround to import PTK-specific events + builtins.__xonsh_env__ = Env() + from xonsh.ptk.shell import events +else: + from xonsh.events import events + +sys.path.insert(0, os.path.dirname(__file__)) + +from rever import __version__ as REVER_VERSION + + +def setup(sphinx): + from xonsh.pyghooks import XonshConsoleLexer + sphinx.add_lexer("xonshcon", XonshConsoleLexer()) + + +# -- General configuration ----------------------------------------------------- + +# Documentation is being built on readthedocs, this will be true. +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' + + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.imgmath', + 'sphinx.ext.inheritance_diagram', 'sphinx.ext.viewcode', + #'sphinx.ext.autosummary', + 'numpydoc', + ] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'rever' +copyright = u'2017, Anthony Scopatz' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = REVER_VERSION.rsplit('.',1)[0] + +# The full version, including alpha/beta/rc tags. +release = REVER_VERSION + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +exclude_patterns = ['api/blank.rst'] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' +#pygments_style = 'friendly' +#pygments_style = 'bw' +#pygments_style = 'fruity' +#pygments_style = 'manni' +#pygments_style = 'tango' +#pygments_style = 'pastie' + +# A list of ignored prefixes for module index sorting. +modindex_common_prefix = ['rever.'] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +#html_theme = 'default' +#html_theme = 'altered_nature' +#html_theme = 'sphinxdoc' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +if not on_rtd: + import cloud_sptheme as csp + + html_theme = 'cloud' + + html_theme_options = { + 'max_width': '1250px', + 'minimal_width': '700px', + 'relbarbgcolor': '#000000', + 'footerbgcolor': '#FFFFE7', + 'sidebarwidth': '322px', + 'sidebarbgcolor': '#e7e7ff', + #'googleanalytics_id': 'UA-41934829-1', + 'stickysidebar': False, + 'highlighttoc': False, + 'externalrefs': False, + 'collapsiblesidebar': True, + 'default_layout_text_size': "100%", # prevents division by zero error + } + + # Add any paths that contain custom themes here, relative to this directory. + html_theme_path = ["_theme", csp.get_theme_dir()] + templates_path = ["_templates_overwrite"] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = '_static/ascii_conch_part_color_tight.png' + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +html_favicon = '_static/magic_conch.ico' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] +html_style = "numpy_friendly.css" + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_use_modindex = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'reverdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'rever.tex', u'rever documentation', + u'Anthony Scopatz', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True + +#Autodocumentation Flags +autodoc_member_order = "groupwise" +autoclass_content = "both" +autosummary_generate = [] + +# Prevent numpy from making silly tables +numpydoc_show_class_members = False + + +# +# Auto-generate some docs +# + +def make_envvars(): + env = Env() + vars = sorted(DEFAULT_DOCS.keys()) + s = ('.. list-table::\n' + ' :header-rows: 0\n\n') + table = [] + ncol = 3 + row = ' {0} - :ref:`${1} <{2}>`' + for i, var in enumerate(vars): + star = '*' if i%ncol == 0 else ' ' + table.append(row.format(star, var, var.lower())) + table.extend([' -']*((ncol - len(vars)%ncol)%ncol)) + s += '\n'.join(table) + '\n\n' + s += ('Listing\n' + '-------\n\n') + sec = ('.. _{low}:\n\n' + '{title}\n' + '{under}\n' + '{docstr}\n\n' + '**configurable:** {configurable}\n\n' + '**default:** {default}\n\n' + '**store_as_str:** {store_as_str}\n\n' + '-------\n\n') + for var in vars: + title = '$' + var + under = '.' * len(title) + vd = env.get_docs(var) + s += sec.format(low=var.lower(), title=title, under=under, + docstr=vd.docstr, configurable=vd.configurable, + default=vd.default, store_as_str=vd.store_as_str) + s = s[:-9] + fname = os.path.join(os.path.dirname(__file__), 'envvarsbody') + with open(fname, 'w') as f: + f.write(s) + + +make_envvars() + +builtins.__xonsh_history__ = None +builtins.__xonsh_env__ = {} +builtins.__xonsh_commands_cache__ = CommandsCache() diff --git a/docs/dependencies.rst b/docs/dependencies.rst new file mode 100644 index 0000000..db61383 --- /dev/null +++ b/docs/dependencies.rst @@ -0,0 +1,28 @@ +Dependencies +============ +Xonsh currently has the following external dependencies, + +*Run Time:* + + #. Python v3.4+ + #. PLY (optional, included with xonsh) + +Pip supports "extra" dependencies in the form of ``xonsh[ptk,linux]``, where +the list in the brackets identify the optional features + +Xonsh currently has the following extras + + #. ``ptk``: prompt-toolkit: + *advanced readline library, line-editing* + #. ``pygments``: *syntax-highlighting* + #. ``proctitle``: setproctitle: *change the title of terminal to reflect the current subprocess* + #. ``linux``: distro: *linux specific platform information* + #. ``mac``: gnureadline: *GNU's featureful version of readline* + #. ``win``: win_unicode_console: *enables the use of Unicode in windows consoles* + +In addition, xonsh integrates with Jupyter, an in-browser REPL, enabling the use of xonsh in jupyter notebooks + +Development Dependencies +======================== + +If you want to develop xonsh, it is extremely recommended to install the dependencies listed in `requirements-docs.txt `_ (to generate documentation) and `requirements-tests.txt `_ (to run the test suite). diff --git a/docs/devguide.rst b/docs/devguide.rst new file mode 120000 index 0000000..798f2aa --- /dev/null +++ b/docs/devguide.rst @@ -0,0 +1 @@ +../CONTRIBUTING.rst \ No newline at end of file diff --git a/docs/envvars.rst b/docs/envvars.rst new file mode 100644 index 0000000..c13d85f --- /dev/null +++ b/docs/envvars.rst @@ -0,0 +1,7 @@ +Environment Variables +===================== +The following displays information about the environment variables that +affect xonsh performance in some way. It also lists their default values, if +applicable. + +.. include:: envvarsbody diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..089264c --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,367 @@ +the xonsh shell +=============== + +.. raw:: html + +

+ + ~ + + ~ +
+
+ +

+ +Xonsh is a Python-powered, cross-platform, Unix-gazing shell language and +command prompt. The language is a superset of Python 3.4+ with additional +shell primitives that you are used to from Bash and IPython. It works on +all major systems including Linux, Mac OSX, and Windows. Xonsh is meant +for the daily use of experts and novices alike. + +**Try it out!** + +.. raw:: html + + +

+ + + +

+
+ + +.. + +========= +Contents +========= +**Installation:** + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + dependencies + linux + osx + windows + customization + +**Guides:** + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + tutorial + tutorial_hist + tutorial_macros + tutorial_xontrib + tutorial_events + tutorial_completers + tutorial_history_backend + tutorial_ptk + bash_to_xsh + python_virtual_environments + +**Configuration & Setup:** + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + xonshrc + xonshconfig + envvars + aliases + xontribs + events + +**News & Media:** + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + talks_and_articles + quotes + + +**Development Spiral:** + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + api/index + advanced_events + devguide/ + changelog + faq + todo + +========== +Comparison +========== +Xonsh is significantly different from most other shells or shell tools. The following +table lists features and capabilities that various tools may or may not share. + +.. list-table:: + :widths: 3 1 1 1 1 1 1 + :header-rows: 1 + :stub-columns: 1 + + * - + - Bash + - zsh + - plumbum + - fish + - IPython + - xonsh + * - Sane language + - + - + - โœ“ + - โœ“ + - โœ“ + - โœ“ + * - Easily scriptable + - โœ“ + - โœ“ + - โœ“ + - โœ“ + - + - โœ“ + * - Native cross-platform support + - + - + - โœ“ + - โœ“ + - โœ“ + - โœ“ + * - Meant as a shell + - โœ“ + - โœ“ + - + - โœ“ + - + - โœ“ + * - Tab completion + - โœ“ + - โœ“ + - + - โœ“ + - โœ“ + - โœ“ + * - Man-page completion + - + - + - + - โœ“ + - + - โœ“ + * - Large standard library + - + - โœ“ + - + - + - โœ“ + - โœ“ + * - Typed variables + - + - + - โœ“ + - โœ“ + - โœ“ + - โœ“ + * - Syntax highlighting + - + - + - + - โœ“ + - in notebook + - w/ prompt-toolkit + * - Pun in name + - โœ“ + - + - โœ“ + - + - + - โœ“ + * - Rich history + - + - + - + - + - + - โœ“ + + + +.. include:: dependencies.rst + + +============ +Contributing +============ +We highly encourage contributions to xonsh! If you would like to contribute, +it is as easy as forking the repository on GitHub, making your changes, and +issuing a pull request. If you have any questions about this process don't +hesitate to ask the mailing list (xonsh@googlegroups.com) or the `Gitter `_ channel. + +See the `Developer's Guide `_ for more information about contributing. + +========== +Contact Us +========== +If you have questions or comments, please send them to the mailing list +xonsh@googlegroups.com, page us on IRC, contact the author directly, or +open an issue on GitHub. +`Join the mailing list here! `_ + +============= +Helpful Links +============= + +* `Documentation `_ +* `Gitter `_ +* `Mailing list `_ +* `IRC: channel #xonsh on OFTC `_ +* `GitHub Repository `_ +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + +.. raw:: html + + Fork me on GitHub + + diff --git a/news/TEMPLATE.rst b/news/TEMPLATE.rst new file mode 100644 index 0000000..ba9f854 --- /dev/null +++ b/news/TEMPLATE.rst @@ -0,0 +1,11 @@ +**Added:** None + +**Changed:** None + +**Deprecated:** None + +**Removed:** None + +**Fixed:** None + +**Security:** None