beam-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From da...@apache.org
Subject [1/2] beam git commit: [BEAM-1320] Add script to generate documentation for the python sdk
Date Mon, 20 Feb 2017 01:40:59 GMT
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 <sourabhbajaj@google.com>
Authored: Thu Feb 16 16:01:36 2017 -0800
Committer: Davor Bonaci <davor@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*


Mime
View raw message