Repository: beam Updated Branches: refs/heads/master d03e3980c -> 92190ba5d
[BEAM-1320] Add script to generate documentation for the python sdk Project: http://git-wip-us.apache.org/repos/asf/beam/repo Commit: http://git-wip-us.apache.org/repos/asf/beam/commit/87f20520 Tree: http://git-wip-us.apache.org/repos/asf/beam/tree/87f20520 Diff: http://git-wip-us.apache.org/repos/asf/beam/diff/87f20520 Branch: refs/heads/master Commit: 87f205207d28d54b3a4e02465c493cb8d626d56b Parents: d03e398 Author: Sourabh Bajaj <sourabhba...@google.com> Authored: Thu Feb 16 16:01:36 2017 -0800 Committer: Davor Bonaci <da...@google.com> Committed: Sun Feb 19 17:40:33 2017 -0800 ---------------------------------------------------------------------- sdks/python/generate_pydoc.sh | 66 ++++++++++++++++++++++++++++++++++++++ sdks/python/pom.xml | 1 - sdks/python/setup.py | 5 +++ sdks/python/tox.ini | 2 ++ 4 files changed, 73 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/beam/blob/87f20520/sdks/python/generate_pydoc.sh ---------------------------------------------------------------------- diff --git a/sdks/python/generate_pydoc.sh b/sdks/python/generate_pydoc.sh new file mode 100755 index 0000000..f96a649 --- /dev/null +++ b/sdks/python/generate_pydoc.sh @@ -0,0 +1,66 @@ +#!/bin/bash +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +# This script will run sphinx to create documentation for python sdk +# +# Use "generate_pydocs.sh" to update documentation in the docs directory. +# +# The exit-code of the script indicates success or a failure. + +# Quit on any errors +set -e + +# Create docs directory if it does not exist +mkdir -p target/docs/source + +# Exclude autogenerated API message definition files that aren't part of SDK. +excluded_internal_clients=(apache_beam/internal/clients/) +python $(type -p sphinx-apidoc) -f -o target/docs/source apache_beam \ + "${excluded_internal_clients[@]}" + +# Remove Cython modules from doc template; they won't load +sed -i -e '/.. automodule:: apache_beam.coders.stream/d' \ + target/docs/source/apache_beam.coders.rst + +# Create the configuration and index files +cat > target/docs/source/conf.py <<'EOF' +import os +import sys + +sys.path.insert(0, os.path.abspath('../../..')) + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', + 'sphinx.ext.viewcode', +] +master_doc = 'index' +html_theme = 'sphinxdoc' +project = 'Apache Beam' +EOF +cat > target/docs/source/index.rst <<'EOF' +.. include:: ./modules.rst +EOF + +# Build the documentation using sphinx +python $(type -p sphinx-build) -q target/docs/source target/docs/_build -c target/docs/source \ + -w "/tmp/sphinx-build.warnings.log" + +# Message is useful only when this script is run locally. In a remote +# test environment, this path will be removed when the test completes. +echo "Browse to file://$PWD/target/docs/_build/index.html" http://git-wip-us.apache.org/repos/asf/beam/blob/87f20520/sdks/python/pom.xml ---------------------------------------------------------------------- diff --git a/sdks/python/pom.xml b/sdks/python/pom.xml index 615ddc5..2b35f4d 100644 --- a/sdks/python/pom.xml +++ b/sdks/python/pom.xml @@ -165,5 +165,4 @@ </plugin> </plugins> </build> - </project> http://git-wip-us.apache.org/repos/asf/beam/blob/87f20520/sdks/python/setup.py ---------------------------------------------------------------------- diff --git a/sdks/python/setup.py b/sdks/python/setup.py index 90a4e53..59c0994 100644 --- a/sdks/python/setup.py +++ b/sdks/python/setup.py @@ -103,6 +103,10 @@ REQUIRED_TEST_PACKAGES = [ 'pyhamcrest>=1.9,<2.0', ] +EXTRA_REQUIRES = { + 'docs': ['Sphinx>=1.5.2,<2.0'], +} + setuptools.setup( name=PACKAGE_NAME, version=PACKAGE_VERSION, @@ -127,6 +131,7 @@ setuptools.setup( install_requires=REQUIRED_PACKAGES, test_suite='nose.collector', tests_require=REQUIRED_TEST_PACKAGES, + extras_require=EXTRA_REQUIRES, zip_safe=False, # PyPI package information. classifiers=[ http://git-wip-us.apache.org/repos/asf/beam/blob/87f20520/sdks/python/tox.ini ---------------------------------------------------------------------- diff --git a/sdks/python/tox.ini b/sdks/python/tox.ini index 20afa58..2f5a7b5 100644 --- a/sdks/python/tox.ini +++ b/sdks/python/tox.ini @@ -30,9 +30,11 @@ deps= nose pep8 pylint + Sphinx commands = python --version python apache_beam/examples/complete/autocomplete_test.py python setup.py test {toxinidir}/run_pylint.sh + {toxinidir}/generate_pydoc.sh passenv = TRAVIS*
