diff --git a/tools/build-index.sh b/tools/build-index.sh new file mode 100755 index 000000000..4b65980c4 --- /dev/null +++ b/tools/build-index.sh @@ -0,0 +1,44 @@ +#!/bin/bash -xe +# +# Licensed 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. + +PUBLISH=$1 + +if [[ -z "$PUBLISH" ]] ; then + echo "usage $0 (build|publish)" + exit 1 +fi + +mkdir -p publish-docs + +# Build the www pages so that openstack-doc-test creates a link to +# www/www-index.html. +if [ "$PUBLISH" = "build" ] ; then + python tools/www-generator.py --source-directory www/ \ + --output-directory publish-docs/www/ + rsync -a www/static/ publish-docs/www/ + # publish-docs/www-index.html is the trigger for openstack-doc-test + # to include the file. + mv publish-docs/www/www-index.html publish-docs/www-index.html +fi +if [ "$PUBLISH" = "publish" ] ; then + + # Publication happens from publish-docs/api-ref to + # developer.openstack.org, so move content around + mkdir publish-docs/api-ref/ + python tools/www-generator.py --source-directory www/ \ + --output-directory publish-docs/api-ref/ + rsync -a www/static/ publish-docs/api-ref/ + # Don't publish this file + rm publish-docs/api-ref/www-index.html +fi diff --git a/tools/www-generator.py b/tools/www-generator.py new file mode 100755 index 000000000..8661c338b --- /dev/null +++ b/tools/www-generator.py @@ -0,0 +1,111 @@ +#!/usr/bin/env python + +# Licensed 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. + +import argparse +import logging +import os +import sys + +import lxml.html +from lxml import etree +import jinja2 + + +def initialize_logging(debug, verbose): + """Initialize the Logger.""" + + logger = logging.getLogger(name='logger') + formatter = logging.Formatter('%(asctime)s %(levelname)-8s %(message)s') + handler = logging.StreamHandler() + handler.setFormatter(formatter) + logger.addHandler(handler) + + if verbose: + logger.setLevel(logging.INFO) + + if debug: + logger.setLevel(logging.DEBUG) + + return logging.getLogger('logger') + + +def parse_command_line_arguments(): + """Parse the command line arguments.""" + parser = argparse.ArgumentParser() + parser.add_argument("--debug", help="Print debugging messages.", + action="store_true", default=False) + parser.add_argument("--verbose", help="Be more verbose.", + action="store_true", default=False) + parser.add_argument("--source-directory", type=str, + default='www', help='') + parser.add_argument("--output-directory", type=str, + default='publish-docs/www', help='') + return parser.parse_args() + + +def main(): + """Entry point for this script.""" + + args = parse_command_line_arguments() + logger = initialize_logging(args.debug, args.verbose) + + try: + loader = jinja2.FileSystemLoader(args.source_directory) + environment = jinja2.Environment(loader=loader) + except Exception as e: + logger.error("initialising template environment failed: %s" % e) + return 1 + + for templateFile in environment.list_templates(): + if not templateFile.endswith('.html'): + continue + + logger.info("generating %s" % templateFile) + + try: + template = environment.get_template(templateFile) + except Exception as e: + logger.error("parsing template %s failed: %s" % + (templateFile, e)) + continue + + try: + output = lxml.html.tostring( + lxml.html.fromstring(template.render()), + pretty_print=True) + except Exception as e: + logger.error("rendering template %s failed: %s" % + (templateFile, e)) + continue + + try: + target_directory = os.path.join(args.output_directory, + os.path.dirname(templateFile)) + target_file = os.path.join(args.output_directory, templateFile) + if not os.path.isdir(target_directory): + logger.debug("creating target directory %s" % + target_directory) + os.makedirs(target_directory) + logger.debug("writing %s" % target_file) + with open(os.path.join(target_file), 'wb') as fh: + fh.write(output.encode('utf8')) + except (IOError, OSError, UnicodeEncodeError) as e: + logger.error("writing %s failed: %s" % (target_file, e)) + continue + + return 0 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/tox.ini b/tox.ini index 2939c8144..64cf2820c 100644 --- a/tox.ini +++ b/tox.ini @@ -42,6 +42,8 @@ commands = openstack-doc-test --check-deletions {posargs} commands = # Build and copy RST Guides {toxinidir}/tools/build-all-rst.sh + # Build website index + {toxinidir}/tools/build-index.sh build # Build DocBook Guides openstack-doc-test --check-build {posargs} @@ -61,6 +63,8 @@ commands = {toxinidir}/tools/build-firstapp-rst.sh # Build and copy API Quick Start {toxinidir}/tools/build-api-quick-start.sh + # Build website index + {toxinidir}/tools/build-index.sh publish [testenv:checklang] # openstack-generate-docbook needs xml2po which cannot be installed in diff --git a/www/index.html b/www/index.html index 8a966c759..26f0c0d5c 100644 --- a/www/index.html +++ b/www/index.html @@ -1,199 +1,58 @@ - - - - - - - - Documentation >> Application Development - - - - - - - - - - - - - - - -
-
-
-

- Need help with a development problem? - - Ask OpenStack - -

-
-
-
- -
- -
-

-

-
-
-
- - - -
-
-
- -
-
-

- Resources for application development on private and public OpenStack clouds. -

-

- You interact with an OpenStack cloud using a number of tools. The tool you choose depends on your use case in the cloud. Here are some starting points. -

-
-
-

- SDK -

- - Software Development Kits - -
-
-

- CLI -

- - Command Line Interfaces - -
-
-

- API -

- - Application Programming Interfaces - -
-
-
-
-
-

- Software Development Kits -

-

- A Software Development Kit (SDK) is a collection of code, examples, and - documentation that helps you to create applications in the language of - your choice on OpenStack clouds. If one of the following SDKs do not - support your language or use case, you can use the API - or one of the other +

+
+
+

Development Resources for OpenStack clouds

+

+ You interact with an OpenStack cloud using a number of tools. The tool you choose depends on your use case in the cloud. Here are some starting points. +

+
+ View SDKs + View APIs + View CLIs +
+ + + +
+
+
+
+

+ Software Development Kits +

+

+ A Software Development Kit (SDK) is a collection of code, examples, and + documentation that helps you to create applications in the language of + your choice on OpenStack clouds. If one of the following SDKs do not + support your language or use case, you can use the API + or one of the other Known SDKs.

Java

-
-

- - Get SDK Now - -

-
-
+
SDK @@ -202,10 +61,15 @@ Apache jclouds +

+ + Get SDK Now + +

-
+
Docs and Resources @@ -227,7 +91,7 @@
-
+
Community Links @@ -270,20 +134,12 @@
-
-
+

Node.js

-
-

- - Get SDK Now - -

-
-
+
SDK @@ -292,10 +148,15 @@ pkgcloud +

+ + Get SDK Now + +

-
+
Docs and Resources @@ -317,7 +178,7 @@
-
+
Community Links @@ -362,14 +223,7 @@

Python

-
-

- - Get SDK Now - -

-
-
+
SDK @@ -378,10 +232,16 @@ libcloud +

+ + Get SDK Now + +

+
-
+
Docs and Resources @@ -408,7 +268,7 @@
-
+
Community Links @@ -457,14 +317,7 @@

Ruby

-
-

- - Get SDK Now - -

-
-
+
SDK @@ -473,10 +326,15 @@ Fog +

+ + Get SDK Now + +

-
+
Docs and Resources @@ -498,7 +356,7 @@
-
+
Community Links @@ -543,14 +401,7 @@

.NET

-
-

- - Get SDK Now - -

-
-
+
SDK @@ -559,10 +410,15 @@ .NET +

+ + Get SDK Now + +

-
+
Docs and Resources @@ -584,7 +440,7 @@
-
+
Community Links @@ -625,24 +481,22 @@

PHP

-
-

- - Get SDK Now - -

-
-
+
SDK
- PHP + PHP +

+ + Get SDK Now + +

-
+
Docs and Resources @@ -664,7 +518,7 @@
-
+
Community Links @@ -702,152 +556,7 @@
-
-

- Command Line Interfaces -

-

- An OpenStack Command Line Interface (CLI) is a text based client that helps you to create scripts for interacting with OpenStack clouds. -

-
-
-
-
- Official CLI -
-
- - OpenStack Client - -
-
- - Block Storage - -
-
- - Compute - -
-
- - Data Processing - -
-
- - Database Service - -
-
- - Identity Service - -
-
- - Image Service - -
-
- - Networking - -
-
- - Object Storage - -
-
- - Orchestration - -
-
- - Shared File Systems - -
-
- - Telemetry - -
-
-
-
-
-
- Docs and Resources -
-
- - Getting Started Guide - -
-
- - CLI Reference Manual - -
-
-
-
-
-
- Community Links -
-
- - Twitter: - - - @openstack - -
-
- - IRC: - - - #openstack - -
-
- - Mailing List: - - - Register - - | - - Archive - -
-
- - Report Issues: - - - Issue Tracker - -
-
- - Support: - - - Ask - -
-
-
-
-
-
+

Application Programming Interfaces

@@ -858,8 +567,6 @@ OpenStack API Quick Start gives you the basics for interacting with the services.

-
-
References @@ -966,8 +673,151 @@
+
+

+ Command Line Interfaces +

+

+ An OpenStack Command Line Interface (CLI) is a text based client that helps you to create scripts for interacting with OpenStack clouds. +

+
+
+
+ Official CLI +
+
+ + OpenStack Client + +
+
+ + Block Storage + +
+
+ + Compute + +
+
+ + Data Processing + +
+
+ + Database Service + +
+
+ + Identity Service + +
+
+ + Image Service + +
+
+ + Networking + +
+
+ + Object Storage + +
+
+ + Orchestration + +
+
+ + Shared File Systems + +
+
+ + Telemetry + +
+
+
+
+
+
+ Docs and Resources +
+
+ + Getting Started Guide + +
+
+ + CLI Reference Manual + +
+
+
+
+
+
+ Community Links +
+
+ + Twitter: + + + @openstack + +
+
+ + IRC: + + + #openstack + +
+
+ + Mailing List: + + + Register + + | + + Archive + +
+
+ + Report Issues: + + + Issue Tracker + +
+
+ + Support: + + + Ask + +
+
+
-
+ +
+ {% endblock content %} + + + + {% include 'templates/header.tmpl' %} + {% block content %}{% endblock %} + {% include 'templates/footer.tmpl' %} + + {% include 'templates/script_footer.tmpl' %} + + diff --git a/www/templates/css.tmpl b/www/templates/css.tmpl new file mode 100644 index 000000000..20b330c8a --- /dev/null +++ b/www/templates/css.tmpl @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + diff --git a/www/templates/default.tmpl b/www/templates/default.tmpl new file mode 100644 index 000000000..d276b9542 --- /dev/null +++ b/www/templates/default.tmpl @@ -0,0 +1 @@ +{%- extends "base.html" %} diff --git a/www/templates/footer.tmpl b/www/templates/footer.tmpl new file mode 100644 index 000000000..30965b148 --- /dev/null +++ b/www/templates/footer.tmpl @@ -0,0 +1,100 @@ + + +
+
+
+
+
+ + +
+
+
+
+
diff --git a/www/templates/header.tmpl b/www/templates/header.tmpl new file mode 100644 index 000000000..58dce3ad3 --- /dev/null +++ b/www/templates/header.tmpl @@ -0,0 +1,149 @@ + + + + + + diff --git a/www/templates/indexbase.tmpl b/www/templates/indexbase.tmpl new file mode 100644 index 000000000..44615ce9f --- /dev/null +++ b/www/templates/indexbase.tmpl @@ -0,0 +1,39 @@ + + + + + + {% block header %}{% endblock %} + OpenStack Docs: {% block pagetitle %}{% endblock %} + + + + + {% include 'templates/css.tmpl' %} + + + + + + {% include 'templates/header.tmpl' %} + {% block content %}{% endblock %} + {% include 'templates/footer.tmpl' %} + + {% include 'templates/script_footer.tmpl' %} + + diff --git a/www/templates/navigation.tmpl b/www/templates/navigation.tmpl new file mode 100644 index 000000000..fd794aec5 --- /dev/null +++ b/www/templates/navigation.tmpl @@ -0,0 +1,29 @@ + diff --git a/www/templates/script_footer.tmpl b/www/templates/script_footer.tmpl new file mode 100644 index 000000000..a51c92868 --- /dev/null +++ b/www/templates/script_footer.tmpl @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/www/www-index.html b/www/www-index.html new file mode 100644 index 000000000..126c2b549 --- /dev/null +++ b/www/www-index.html @@ -0,0 +1,9 @@ + + + + + +