From 120cfa922907839b9cc05060830ef60cd761698f Mon Sep 17 00:00:00 2001 From: jimmylai Date: Mon, 22 Jul 2019 13:09:24 -0700 Subject: [PATCH] add sphinx autodoc templates and docs CI job --- .circleci/config.yml | 64 +++++--- .gitignore | 1 + docs/source/conf.py | 209 ++++++++++++++++++++++++ docs/source/index.rst | 25 +++ docs/source/modules/libcst.nodes.rst | 7 + docs/source/modules/libcst.parser.rst | 7 + docs/source/modules/libcst.visitors.rst | 6 + requirements-dev.txt | 1 + setup.py | 2 +- tox.ini | 10 +- 10 files changed, 307 insertions(+), 25 deletions(-) create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/modules/libcst.nodes.rst create mode 100644 docs/source/modules/libcst.parser.rst create mode 100644 docs/source/modules/libcst.visitors.rst diff --git a/.circleci/config.yml b/.circleci/config.yml index 5b4e3b63..4412317b 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -2,33 +2,53 @@ # # Check https://circleci.com/docs/2.0/language-python/ for more details # -version: 2 +version: 2.1 workflows: version: 2 test: jobs: - lint + - docs - pyre - - test-3.7 - - test-3.6 + - test-37 + - test-36 -tox_command: &tox_command - steps: - - checkout - - run: - name: install tox - command: pip install --user tox - - run: - name: run tox - command: ~/.local/bin/tox +commands: + tox: + description: "setup tox env and run tox command giving env parameter" + parameters: + env: + type: string + default: test + steps: + - checkout + - run: + name: install tox + command: pip install --user tox + - run: + name: run tox + command: ~/.local/bin/tox -e << parameters.env >> jobs: lint: - <<: *tox_command + docker: + - image: circleci/python:3.7 + steps: + - tox: + env: "lint" + + docs: docker: - image: circleci/python:3.7 environment: - TOXENV: lint + TOXENV: docs + steps: + - tox: + env: "docs" + - store_artifacts: + path: docs/build + destination: doc + pyre: docker: - image: circleci/python:3.7 @@ -43,16 +63,16 @@ jobs: pip install -r requirements.txt -r requirements-dev.txt pyre check - test-3.7: - <<: *tox_command + test-37: docker: - image: circleci/python:3.7 - environment: - TOXENV: py37 + steps: + - tox: + env: "docs" - test-3.6: - <<: *tox_command + test-36: docker: - image: circleci/python:3.6 - environment: - TOXENV: py36 + steps: + - tox: + env: "docs" diff --git a/.gitignore b/.gitignore index cb4efa68..b6be92c3 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ .pyre/ __pycache__/ .tox/ +docs/build/ diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..cc4f6ac4 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,209 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'LibCST' +copyright = '2019, Facebook' +author = 'Benjamin Woodruff, Jennifer Taylor, Carl Meyer, Jimmy Lai, Ray Zeng' + +# The short X.Y version +version = '' +# The full version, including alpha/beta/rc tags +release = '' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# 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.autosummary', + 'sphinx.ext.todo', + 'sphinx.ext.githubpages', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# 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. +# +# html_theme_options = {} + +# 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'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'LibCSTdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'LibCST.tex', 'LibCST Documentation', + 'Benjamin Woodruff, Jennifer Taylor', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'libcst', 'LibCST Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'LibCST', 'LibCST Documentation', + author, 'LibCST', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + +# -- Extension configuration ------------------------------------------------- + + +# -- Options for todo extension ---------------------------------------------- + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + +# -- autodoc customization +def strip_class_signature(app, what, name, obj, options, signature, return_annotation): + if what == 'class': + return (None, return_annotation) + return (signature, return_annotation) + + +def strip_class_signature_docstring(app, what, name, obj, options, lines): + if what == 'class': + cls_name = name.split('.')[-1] + if lines and lines[0].startswith(cls_name): + while lines: + del lines[0] + +def setup(app): + app.connect('autodoc-process-signature', strip_class_signature) + app.connect('autodoc-process-docstring', strip_class_signature_docstring) diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..b0d97c67 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,25 @@ +.. LibCST documentation master file, created by + sphinx-quickstart on Wed Jul 17 17:05:21 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to LibCST's documentation! +================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + +.. autosummary:: + :toctree: modules + + libcst.nodes + libcst.parser + libcst.visitors + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/modules/libcst.nodes.rst b/docs/source/modules/libcst.nodes.rst new file mode 100644 index 00000000..2f43f246 --- /dev/null +++ b/docs/source/modules/libcst.nodes.rst @@ -0,0 +1,7 @@ +libcst.nodes +============ + +.. automodule:: libcst.nodes + :members: + :imported-members: + :undoc-members: diff --git a/docs/source/modules/libcst.parser.rst b/docs/source/modules/libcst.parser.rst new file mode 100644 index 00000000..ff4085f0 --- /dev/null +++ b/docs/source/modules/libcst.parser.rst @@ -0,0 +1,7 @@ +libcst.parser +============= + +.. automodule:: libcst.parser + :members: + :imported-members: + :undoc-members: diff --git a/docs/source/modules/libcst.visitors.rst b/docs/source/modules/libcst.visitors.rst new file mode 100644 index 00000000..21b26c5c --- /dev/null +++ b/docs/source/modules/libcst.visitors.rst @@ -0,0 +1,6 @@ +libcst.visitors +=============== + +.. automodule:: libcst.visitors + :members: + diff --git a/requirements-dev.txt b/requirements-dev.txt index a325679a..56f89529 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -2,3 +2,4 @@ black==19.3b0 flake8==3.7.8 isort==4.3.20 pyre-check==0.0.27 +Sphinx==2.1.2 diff --git a/setup.py b/setup.py index 8d757b1d..1757e123 100644 --- a/setup.py +++ b/setup.py @@ -29,6 +29,6 @@ setuptools.setup( "typing_inspect", ], extras_require={ - "dev": ["black", "flake8", "isort", "pyre-check"], + "dev": ["black", "flake8", "isort", "pyre-check", "Sphinx"], } ) diff --git a/tox.ini b/tox.ini index 4e719e47..96543b4b 100644 --- a/tox.ini +++ b/tox.ini @@ -1,10 +1,9 @@ [tox] -envlist = py36, py37, lint +envlist = py36, py37, lint, docs [testenv] deps = -rrequirements.txt -rrequirements-dev.txt - commands = isort --recursive libcst/ black libcst/ @@ -18,3 +17,10 @@ commands = flake8 isort --check-only black --check libcst/ + +[testenv:docs] +deps = + -rrequirements.txt + -rrequirements-dev.txt +commands = + sphinx-build docs/source/ docs/build/