Repository: beam-site Updated Branches: refs/heads/asf-site 7937818f5 -> b3d322402
[BEAM-1320] Update release guide to create pydocs Project: http://git-wip-us.apache.org/repos/asf/beam-site/repo Commit: http://git-wip-us.apache.org/repos/asf/beam-site/commit/6686137c Tree: http://git-wip-us.apache.org/repos/asf/beam-site/tree/6686137c Diff: http://git-wip-us.apache.org/repos/asf/beam-site/diff/6686137c Branch: refs/heads/asf-site Commit: 6686137c3096004dc77b2078327c78a2723fcf57 Parents: 7937818 Author: Sourabh Bajaj <[email protected]> Authored: Wed Feb 22 14:15:28 2017 -0800 Committer: Sourabh Bajaj <[email protected]> Committed: Wed Feb 22 14:15:28 2017 -0800 ---------------------------------------------------------------------- src/_includes/header.html | 6 +++++- src/contribute/release-guide.md | 20 +++++++++++++++++--- src/documentation/sdks/java.md | 2 +- src/documentation/sdks/pydoc/current.md | 9 +++++++++ src/documentation/sdks/pydoc/index.md | 9 +++++++++ src/documentation/sdks/python.md | 6 +++--- 6 files changed, 44 insertions(+), 8 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/beam-site/blob/6686137c/src/_includes/header.html ---------------------------------------------------------------------- diff --git a/src/_includes/header.html b/src/_includes/header.html index d44e0dc..a3a54e0 100644 --- a/src/_includes/header.html +++ b/src/_includes/header.html @@ -50,6 +50,10 @@ alt="External link."></a> </li> <li><a href="{{ site.baseurl }}/documentation/sdks/python/">Python SDK</a></li> +<!-- <li><a href="{{ site.baseurl }}/documentation/sdks/pydoc/{{ site.release_latest }}/" target="_blank">Python SDK API Reference <img src="{{ site.baseurl }}/images/external-link-icon.png" + width="14" height="14" + alt="External link."></a> + </li> --> <li role="separator" class="divider"></li> <li class="dropdown-header">Runners</li> <li><a href="{{ site.baseurl }}/documentation/runners/capability-matrix/">Capability Matrix</a></li> @@ -74,7 +78,7 @@ <li class="dropdown-header">Technical References</li> <li><a href="{{ site.baseurl }}/contribute/design-principles/">Design Principles</a></li> <li><a href="{{ site.baseurl }}/contribute/work-in-progress/">Ongoing Projects</a></li> - <li><a href="{{ site.baseurl }}/contribute/source-repository/">Source Repository</a></li> + <li><a href="{{ site.baseurl }}/contribute/source-repository/">Source Repository</a></li> <li role="separator" class="divider"></li> <li class="dropdown-header">Promotion</li> <li><a href="{{ site.baseurl }}/contribute/presentation-materials/">Presentation Materials</a></li> http://git-wip-us.apache.org/repos/asf/beam-site/blob/6686137c/src/contribute/release-guide.md ---------------------------------------------------------------------- diff --git a/src/contribute/release-guide.md b/src/contribute/release-guide.md index 7bba5ee..db0b558 100644 --- a/src/contribute/release-guide.md +++ b/src/contribute/release-guide.md @@ -278,6 +278,14 @@ Copy the source release to the dev repository of `dist.apache.org`. 1. Verify that files are [present](https://dist.apache.org/repos/dist/dev/beam). +### Build the Pydoc API reference + +Create the Python SDK documentation using sphinx by running a helper script. +``` +cd sdks/python && ./generate_pydoc.sh +``` +By default the Pydoc is generated in `sdks/python/target/docs/_build`. Let `${PYDOC_ROOT}` be the absolute path to `_build`. + ### Propose a pull request for website updates The final step of building the candidate is to propose a website pull request. @@ -297,13 +305,19 @@ Add the new Javadoc to [SDK API Reference page]({{ site.baseurl }}/documentation * Set up the necessary git commands to account for the new and deleted files from the javadoc. * Update the Javadoc link on this page to point to the new version (in `src/documentation/sdks/javadoc/current.md`). +#### Create Pydoc +Add the new Pydoc to [SDK API Reference page]({{ site.baseurl }}/documentation/sdks/pydoc/) page, as follows: + +* Copy the generated Pydoc into the website repository: `cp -r ${PYDOC_ROOT} documentation/sdks/pydoc/${VERSION}`. +* Update the Pydoc link on this page to point to the new version (in `src/documentation/sdks/pydoc/current.md`). + Finally, propose a pull request with these changes. (Donât merge before finalizing the release.) ### Checklist to proceed to the next step 1. Maven artifacts deployed to the staging repository of [repository.apache.org](https://repository.apache.org/content/repositories/) 1. Source distribution deployed to the dev repository of [dist.apache.org](https://dist.apache.org/repos/dist/dev/beam/) -1. Website pull request proposed to list the [release]({{ site.baseurl }}/use/releases/) and publish the [API reference manual]({{ site.baseurl }}/learn/sdks/javadoc/) +1. Website pull request proposed to list the [release]({{ site.baseurl }}/use/releases/), publish the [Java API reference manual]({{ site.baseurl }}/documentation/sdks/javadoc/), and publish the [Python API reference manual]({{ site.baseurl }}/documentation/sdks/pydoc/). ********** @@ -402,7 +416,7 @@ Create a new Git tag for the released version by copying the tag for the final r ### Merge website pull request -Merge the website pull request to [list the release]({{ site.baseurl }}/use/releases/) and publish the [API reference manual]({{ site.baseurl }}/learn/sdks/javadoc/) created earlier. +Merge the website pull request to [list the release]({{ site.baseurl }}/use/releases/), publish the [Python API reference manual]({{ site.baseurl }}/documentation/sdks/pydoc/), and the [Java API reference manual]({{ site.baseurl }}/documentation/sdks/javadoc/) created earlier. ### Mark the version as released in JIRA @@ -412,7 +426,7 @@ In JIRA, inside [version management](https://issues.apache.org/jira/plugins/serv * Maven artifacts released and indexed in the [Maven Central Repository](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache.beam%22) * Source distribution available in the release repository of [dist.apache.org](https://dist.apache.org/repos/dist/release/beam/) -* Website pull request to [list the release]({{ site.baseurl }}/use/releases/) and publish the [API reference manual]({{ site.baseurl }}/learn/sdks/javadoc/) merged +* Website pull request to [list the release]({{ site.baseurl }}/use/releases/) and publish the [API reference manual]({{ site.baseurl }}/documentation/sdks/javadoc/) merged * Release tagged in the source code repository * Release version finalized in JIRA http://git-wip-us.apache.org/repos/asf/beam-site/blob/6686137c/src/documentation/sdks/java.md ---------------------------------------------------------------------- diff --git a/src/documentation/sdks/java.md b/src/documentation/sdks/java.md index 0ec2353..540eec4 100644 --- a/src/documentation/sdks/java.md +++ b/src/documentation/sdks/java.md @@ -13,7 +13,7 @@ The Java SDK for Apache Beam provides a simple, powerful API for building both b Get started with the [Beam Programming Model]({{ site.baseurl }}/learn/programming-guide/) to learn the basic concepts that apply to all SDKs in Beam. -See the [Java API Reference]({{ site.baseurl }}/learn/sdks/javadoc/) for more information on individual APIs. +See the [Java API Reference]({{ site.baseurl }}/documentation/sdks/javadoc/) for more information on individual APIs. ## Supported Features http://git-wip-us.apache.org/repos/asf/beam-site/blob/6686137c/src/documentation/sdks/pydoc/current.md ---------------------------------------------------------------------- diff --git a/src/documentation/sdks/pydoc/current.md b/src/documentation/sdks/pydoc/current.md new file mode 100644 index 0000000..e48b865 --- /dev/null +++ b/src/documentation/sdks/pydoc/current.md @@ -0,0 +1,9 @@ +--- +layout: default +title: "Apache Beam Pydoc" +permalink: /documentation/sdks/pydoc/current/ +--- +<!-- redirect_to: /documentation/sdks/pydoc/0.5.0/ --> + +<!-- TODO: Remove the line below and uncomment the redirect above at time of release --> +Please watch this space for the upcoming Python SDK release. http://git-wip-us.apache.org/repos/asf/beam-site/blob/6686137c/src/documentation/sdks/pydoc/index.md ---------------------------------------------------------------------- diff --git a/src/documentation/sdks/pydoc/index.md b/src/documentation/sdks/pydoc/index.md new file mode 100644 index 0000000..c538cce --- /dev/null +++ b/src/documentation/sdks/pydoc/index.md @@ -0,0 +1,9 @@ +--- +layout: default +title: "Apache Beam Pydoc" +permalink: /documentation/sdks/pydoc/ +--- +<!-- redirect_to: /documentation/sdks/pydoc/current/ --> + +<!-- TODO: Remove the line below and uncomment the redirect above at time of release --> +Please watch this space for the upcoming Python SDK release. http://git-wip-us.apache.org/repos/asf/beam-site/blob/6686137c/src/documentation/sdks/python.md ---------------------------------------------------------------------- diff --git a/src/documentation/sdks/python.md b/src/documentation/sdks/python.md index 6af6352..89fbb06 100644 --- a/src/documentation/sdks/python.md +++ b/src/documentation/sdks/python.md @@ -1,6 +1,6 @@ --- layout: default -title: "Beam Python SDK" +title: "Apache Beam Python SDK" permalink: /documentation/sdks/python/ --- # Apache Beam Python SDK @@ -9,9 +9,9 @@ The Python SDK for Apache Beam provides a simple, powerful API for building batc ## Get Started with the Python SDK -Get started with the [Beam Programming Guide]({{ site.baseurl }}/learn/programming-guide) to learn the basic concepts that apply to all SDKs in Beam. +Get started with the [Beam Programming Guide]({{ site.baseurl }}/learn/programming-guide) to learn the basic concepts that apply to all SDKs in Beam. Then, follow the [Beam Python SDK Quickstart]({{ site.baseurl }}/get-started/quickstart-py) to set up your Python development environment, get the Beam SDK for Python, and run an example pipeline. -Then, follow the [Beam Python SDK Quickstart]({{ site.baseurl }}/get-started/quickstart-py) to set up your Python development environment, get the Beam SDK for Python, and run an example pipeline. +See the [Python API Reference]({{ site.baseurl }}/documentation/sdks/pydoc/) for more information on individual APIs. ## Python Type Safety
