Skip to content

Commit fcfa4a7

Browse files
soo-awssoo-aws
committed
initial checking to github repo for java dev guide v2
0 parents  commit fcfa4a7

31 files changed

+2649
-0
lines changed

‎LICENSE

+282
Large diffs are not rendered by default.

‎Makefile

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4+
#
5+
# This file is licensed under the Apache License, Version 2.0 (the "License").
6+
# You may not use this file except in compliance with the License. A copy of the
7+
# License is located at
8+
#
9+
# http://aws.amazon.com/apache2.0/
10+
#
11+
# This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
12+
# OF ANY KIND, either express or implied. See the License for the specific
13+
# language governing permissions and limitations under the License.
14+
#
15+
# ------------------------------------------------------------------
16+
# A simple Makefile to build docs with 'make'.
17+
# ------------------------------------------------------------------
18+
all:
19+
python build_docs.py
20+
21+
html:
22+
python build_docs.py html

‎README.rst

+112
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
2+
3+
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
4+
International License (the "License"). You may not use this file except in compliance with the
5+
License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/.
6+
7+
This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
8+
either express or implied. See the License for the specific language governing permissions and
9+
limitations under the License.
10+
11+
########################
12+
aws-java-developer-guide
13+
########################
14+
15+
This repository contains source content for the official `AWS Java Developer Guide`_. The source
16+
code for the `AWS SDK for Java`_ is also on GitHub, at https://github.com/aws/aws-sdk-java-v2/.
17+
18+
The guide content is written in reStructuredText_ and built using Sphinx_. It relies upon content
19+
which is provided in the AWS documentation team's `shared content`_ and `SDK examples`_
20+
repositories.
21+
22+
23+
Reporting issues
24+
================
25+
26+
You can use the Issues_ section of this repository to report problems in the documentation. *When
27+
submitting an issue, please indicate*:
28+
29+
* what page (a URL or filename is best) the issue occurs on.
30+
31+
* what the issue is, using as much detail as you can provide. For many issues, this might be as
32+
simple as "The page has a typo; the word 'complie' in the third paragraph shoud be 'compile'." If
33+
the issue is more complex, please describe it with enough detail that it's clear to the AWS
34+
documentation team what the problem is.
35+
36+
37+
Contributing fixes and updates
38+
==============================
39+
40+
To contribute your own documentation fixes or updates, please use the Github-standard procedures for
41+
`forking the repository`_ and submitting a `pull request`_.
42+
43+
Note that many common substitutions_ and extlinks_ found in these docs are sourced from the `shared
44+
content`_ repository--if you see a substitution used that is not declared at the top of the source
45+
file or in the ``_includes.txt`` file, then it is probably defined in the shared content.
46+
47+
48+
Building the documentation
49+
--------------------------
50+
51+
If you are planning to contribute to the docs, you should build your changes and review them before
52+
submitting your pull request.
53+
54+
**To build the docs:**
55+
56+
1. Make sure that you have downloaded and installed Sphinx_.
57+
2. Run the ``build_docs.py`` script in the repository's root directory.
58+
59+
``build_docs.py`` can take any of the `available Sphinx builders`_ as its argument. For example,
60+
to build the docs into a single HTML page, you can use the ``singlehtml`` target, like so::
61+
62+
python build_docs.py singlehtml
63+
64+
The build process will automatically download a snapshot of its dependencies, combine them in the
65+
``doc_build`` directory and will then generate output into the ``doc_output`` directory.
66+
67+
68+
Code examples in the documentation
69+
----------------------------------
70+
71+
The code examples featured in this documentation can be found in a separate repository:
72+
`aws-doc-sdk-examples <https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java>`_. Full
73+
code and build files are included, so you can build and run any of the provided examples yourself.
74+
75+
In addition to examples in Java, you'll also find examples for each of the other AWS SDKs. If you
76+
find issues with any of the examples, you can submit issues or fork the repository and submit a pull
77+
request!
78+
79+
The code examples are provided under the *Apache 2.0* open source license. See the example
80+
repository's `README <https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/README.rst>`_ for
81+
more details.
82+
83+
84+
Copyright and license
85+
=====================
86+
87+
All content in this repository, unless otherwise stated, is Copyright © 2010-2016, Amazon Web
88+
Services, Inc. or its affiliates. All rights reserved.
89+
90+
Except where otherwise noted, this work is licensed under a `Creative Commons
91+
Attribution-NonCommercial-ShareAlike 4.0 International License
92+
<http://creativecommons.org/licenses/by-nc-sa/4.0/>`_ (the "License"). Use the preceding link for a
93+
human-readable summary of the license terms. The full license text is available at:
94+
http://creativecommons.org/licenses/by-nc-sa/4.0/legalcode and in the LICENSE file accompanying this
95+
repository.
96+
97+
.. =================================================================================
98+
.. Links used in the README. For sanity's sake, keep this list sorted alphabetically
99+
.. =================================================================================
100+
101+
.. _`available sphinx builders`: http://www.sphinx-doc.org/en/stable/builders.html
102+
.. _`aws java developer guide`: http://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/welcome.html
103+
.. _`aws sdk for java`: https://aws.amazon.com/sdk-for-java/
104+
.. _`forking the repository`: https://help.github.com/articles/fork-a-repo/
105+
.. _`pull request`: https://help.github.com/articles/using-pull-requests/
106+
.. _`shared content`: https://github.com/awsdocs/aws-doc-shared-content
107+
.. _`sdk examples`: https://github.com/awsdocs/aws-doc-sdk-examples
108+
.. _extlinks: http://www.sphinx-doc.org/en/stable/ext/extlinks.html
109+
.. _issues: https://github.com/awsdocs/aws-java-developer-guide/issues
110+
.. _restructuredtext: http://docutils.sourceforge.net/rst.html
111+
.. _sphinx: http://www.sphinx-doc.org/en/stable/
112+
.. _substitutions: http://www.sphinx-doc.org/en/stable/rest.html#substitutions

‎build_docs.py

+189
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
#!/usr/bin/env python
2+
# -*- coding: utf-8 -*-
3+
#
4+
# Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
5+
#
6+
# This file is licensed under the Apache License, Version 2.0 (the "License").
7+
# You may not use this file except in compliance with the License. A copy of the
8+
# License is located at
9+
#
10+
# http://aws.amazon.com/apache2.0/
11+
#
12+
# This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
13+
# OF ANY KIND, either express or implied. See the License for the specific
14+
# language governing permissions and limitations under the License.
15+
#
16+
# ------------------------------------------------------------------
17+
# Documentation build script for AWS Sphinx documentation on GitHub.
18+
# ------------------------------------------------------------------
19+
20+
import sys, os
21+
import subprocess
22+
import shutil
23+
24+
SPHINX_MISSING = """
25+
You must have Sphinx installed to use this script!
26+
27+
Go to http://www.sphinx-doc.org for information about installing and using
28+
Sphinx.
29+
"""
30+
31+
FAILED_CHECKOUT = """
32+
Couldn't clone repository. Please make sure that you have 'git' installed and
33+
that you can access GitHub repositories using SSH.
34+
"""
35+
36+
# The file to load extra dependencies from.
37+
DEPENDENCIES_FILE = 'dependencies.txt'
38+
DEPENDENCIES_DIR = 'build_dependencies'
39+
40+
BUILD_DIR = 'doc_build'
41+
OUTPUT_DIR = 'doc_output'
42+
SOURCE_DIR = 'doc_source'
43+
44+
45+
def check_and_remove_dir(dir_name):
46+
"""Check to see if the named directory exists. If it does, then remove it.
47+
Throw an exception if the directory can't be removed."""
48+
49+
if os.path.exists(dir_name):
50+
print("Removing directory: " + dir_name)
51+
try:
52+
shutil.rmtree(dir_name)
53+
except:
54+
print("Couldn't remove " + dir_name)
55+
print("Remove this directory before building!")
56+
sys.exit(1)
57+
58+
59+
def copy_dir_contents_with_overwrite(input_dir_name, output_dir_name):
60+
"""Copy the contents of a directory into another, overwriting files if they
61+
exist."""
62+
63+
# if output_dir_name isn't a location, make it so.
64+
if not os.path.exists(output_dir_name):
65+
os.makedirs(output_dir_name)
66+
67+
dir_entries = os.listdir(input_dir_name)
68+
69+
for dir_entry in dir_entries:
70+
input_path = os.path.join(input_dir_name, dir_entry)
71+
output_path = os.path.join(output_dir_name, dir_entry)
72+
73+
if os.path.isdir(input_path):
74+
copy_dir_contents_with_overwrite(input_path, output_path)
75+
else:
76+
shutil.copyfile(input_path, output_path)
77+
78+
79+
def clone_and_copy_dependency(git_url, dep, subdir = ''):
80+
print("Getting content from dependency: " + git_url)
81+
try:
82+
subprocess.check_call(['git', 'clone', '--depth', '1', git_url,
83+
os.path.join(DEPENDENCIES_DIR, dep)])
84+
except:
85+
print(FAILED_CHECKOUT)
86+
sys.exit(1)
87+
88+
# copy the contents of the subdir into the build directory.
89+
path_to_copy = os.path.join(DEPENDENCIES_DIR, dep, subdir)
90+
copy_dir_contents_with_overwrite(path_to_copy, BUILD_DIR)
91+
92+
93+
def run():
94+
# try to import requirements, and complain if they can't be found.
95+
try:
96+
from sphinx import version_info as sphinx_version
97+
print("Using Sphinx version %s.%s.%s" % sphinx_version[0:3])
98+
except:
99+
print(SPHINX_MISSING)
100+
sys.exit(1)
101+
102+
build_target = 'html' # by default
103+
cmd_switches = []
104+
105+
for arg in sys.argv[1:]:
106+
if arg.startswith('--'):
107+
cmd_switches.append(arg)
108+
else:
109+
# the only non-switch argument is the output format.
110+
build_target = arg
111+
112+
print("Building '%s' target." % build_target)
113+
114+
#
115+
# Step 0: empty the build dir if it's there.
116+
#
117+
check_and_remove_dir(BUILD_DIR)
118+
check_and_remove_dir(DEPENDENCIES_DIR)
119+
check_and_remove_dir(OUTPUT_DIR)
120+
121+
# Step 1: Load any dependencies. Dependencies consist of a tuple: a git repository and a
122+
# subdirectory to copy.
123+
dependencies = []
124+
if os.path.exists(DEPENDENCIES_FILE):
125+
os.mkdir(DEPENDENCIES_DIR)
126+
dep_num = 0
127+
dep_file_contents = open(DEPENDENCIES_FILE, 'r').readlines()
128+
for line in dep_file_contents:
129+
# ignore comments
130+
bare_line = line.strip()
131+
if bare_line == '':
132+
continue
133+
elif not bare_line.startswith('#'):
134+
(git_url, subdir) = line.split()
135+
if subdir == None:
136+
subdir = ''
137+
clone_and_copy_dependency(git_url, str(dep_num), subdir)
138+
dep_num += 1
139+
140+
#
141+
# Step 2: copy the contents of SOURCE_DIR into the BUILD_DIR.
142+
#
143+
print("Copying doc sources from %s to %s" % (SOURCE_DIR, BUILD_DIR))
144+
copy_dir_contents_with_overwrite(SOURCE_DIR, BUILD_DIR)
145+
146+
#
147+
# Append the contents of any files in the 'build/_conf' directory to the
148+
# project's conf.py file (so that shared content can add commonly-used
149+
# extlinks, etc.).
150+
#
151+
conf_py_path = os.path.join(BUILD_DIR, 'conf.py')
152+
extra_conf_path = os.path.join(BUILD_DIR, '_conf')
153+
# first, open the conf.py file for appending...
154+
with open(conf_py_path, 'a') as conf_file:
155+
# now, add the contents of each file in alpha-sorted order.
156+
for filename in sorted(os.listdir(extra_conf_path)):
157+
print(" - %s" % filename)
158+
conf_file.write('# ** added by extra conf file: %s **\n' % filename)
159+
with open(os.path.join(extra_conf_path, filename), 'r') as extra_conf_file:
160+
conf_file.write(extra_conf_file.read())
161+
conf_file.write('# ** end of content from %s **\n' % filename)
162+
163+
#
164+
# Step 3: build the docs
165+
#
166+
print("Building documentation.")
167+
try:
168+
subprocess.check_call(['sphinx-build', '-b', build_target, BUILD_DIR,
169+
OUTPUT_DIR])
170+
except:
171+
print(FAILED_CHECKOUT)
172+
sys.exit(1)
173+
174+
#
175+
# Step 4: Clean up the build dir and shared content.
176+
#
177+
if '--noclean' not in cmd_switches:
178+
print("Cleaning up.")
179+
check_and_remove_dir(BUILD_DIR)
180+
check_and_remove_dir(DEPENDENCIES_DIR)
181+
182+
print("Finished! You'll find the built docs in the '%s' directory." %
183+
OUTPUT_DIR)
184+
185+
186+
# If run from the command-line...
187+
if __name__ == '__main__':
188+
run()
189+

‎dependencies.txt

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Dependencies for the AWS SDK for Java Developer Guide, which are copied into the build directory
2+
# during a build.
3+
#
4+
# The format of this file is simple: each line represents a single dependency, consisting of a Git
5+
# URL and an optional sub-directory within the repository. If the sub-directory is given, then
6+
# everything within it and down is copied.
7+
#
8+
# Git URL Subdirectory to copy
9+
# --------------------------------------------------- ------------------------------------------
10+
https://github.com/awsdocs/aws-doc-shared-content.git sphinx_shared
11+
https://github.com/awsdocs/aws-doc-sdk-examples.git java
12+

‎doc_source/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
example_code

‎doc_source/_includes.txt

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
2+
3+
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
4+
International License (the "License"). You may not use this file except in compliance with the
5+
License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/.
6+
7+
This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
8+
either express or implied. See the License for the specific language governing permissions and
9+
limitations under the License.
10+
11+
.. project-specific includes for this project.
12+
13+
.. |sdk-java-dl| replace:: https://sdk-for-java.amazonwebservices.com/latest/aws-java-sdk.zip
14+
.. _aws_java_api_v2_url: 'http://aws-java-sdk-javadoc.s3-website-us-west-2.amazonaws.com/latest/'
15+
16+
.. |sdk-java-github| replace:: AWS SDK for Java 2.0 (GitHub)
17+
.. _sdk-java-github: https://github.com/aws/aws-java-sdk-v2
18+
19+
.. |sdk-java-github-v1| replace:: AWS SDK for Java 1.x (GitHub)
20+
.. _sdk-java-github-v1: https://github.com/aws/aws-sdk-java
21+
22+
.. |mvn| replace:: Maven
23+
.. |mvnlong| replace:: Apache |mvn|
24+
25+
.. _Gradle: https://gradle.com/
26+
.. _Maven: https://maven.apache.org/
27+
.. _mvn: Maven_
28+
.. _mvnlong: Maven_
29+
30+
.. |cwclient| replace:: :aws-java-class:`AmazonCloudWatchClient <services/cloudwatch/AmazonCloudWatchClient>`
31+
.. |cweclient| replace:: :aws-java-class:`AmazonCloudWatchEventsClient <services/cloudwatchevents/AmazonCloudWatchEventsClient>`
32+
.. |ddbclient| replace:: :aws-java-class:`AmazonDynamoDB <services/dynamodbv2/AmazonDynamoDBClient>`
33+
.. |ec2client| replace:: :aws-java-class:`AmazonEC2Client <services/ec2/AmazonEC2Client>`
34+
.. |iamclient| replace:: :aws-java-class:`AmazonIdentityManagementClient <services/identitymanagement/AmazonIdentityManagementClient>`
35+
.. |s3client| replace:: :aws-java-class:`AmazonS3 <services/s3/AmazonS3Client>`
36+
.. |sqsclient| replace:: :aws-java-class:`AmazonSQS <services/sqs/AmazonSQSClient>`
37+
.. |xfermgr| replace:: :aws-java-class:`TransferManager <services/s3/transfer/TransferManager>`

0 commit comments

Comments
 (0)