From 39b5ecfbd9bbda594a442ed2cdda550f572b50d4 Mon Sep 17 00:00:00 2001 From: Andreas Jaeger Date: Sat, 21 Nov 2015 19:26:32 +0100 Subject: [PATCH] Improve index page layout Split up draft guides under separate heading and remove draft word for easier review. The output looks now basically like: Generated documents admin-guide-cloud contributor-guide networking-guide user-guide user-guide-admin Draft Guides arch-design-rst config-ref-rst image-guide-rst install-guide-debian install-guide-obs install-guide-rdo install-guide-ubuntu Also, create separate tool openstack-indexpage that only generates index page. Change-Id: Ic68a674918f18dc37f8b9fa4e9d9f529a8ad131e --- os_doc_tools/doctest.py | 66 +------------ os_doc_tools/index.py | 96 +++++++++++++++++++ .../separate-index-cce0ae4286f1da53.yaml | 4 + setup.cfg | 1 + 4 files changed, 104 insertions(+), 63 deletions(-) create mode 100644 os_doc_tools/index.py create mode 100644 releasenotes/notes/separate-index-cce0ae4286f1da53.yaml diff --git a/os_doc_tools/doctest.py b/os_doc_tools/doctest.py index a5ceba94..fadde0e3 100755 --- a/os_doc_tools/doctest.py +++ b/os_doc_tools/doctest.py @@ -50,6 +50,7 @@ from lxml import etree from oslo_config import cfg import os_doc_tools +from os_doc_tools import index from os_doc_tools import jsoncheck from os_doc_tools.openstack.common import log @@ -1241,67 +1242,6 @@ def find_affected_books(rootdir, book_exceptions, file_exceptions, return books -def generate_index_file(): - """Generate index.html file in publish_path.""" - - publish_path = get_publish_path() - if not os.path.isdir(publish_path): - os.mkdir(publish_path) - - index_file = open(os.path.join(get_publish_path(), 'index.html'), 'w') - - index_file.write( - '\n' - '\n' - '\n' - '

Results of checkbuild

\n') - - links = {} - for root, dirs, files in os.walk(publish_path): - - dirs[:] = [d for d in dirs if d not in ['common', 'webapp', 'content', - 'www']] - - # Ignore top-level index.html files - if root == publish_path: - continue - - if os.path.isfile(os.path.join(root, 'content/index.html')): - path = os.path.relpath(root, publish_path) - links[path] = ('%s\n' % - (path, path)) - elif os.path.isfile(os.path.join(root, 'index.html')): - path = os.path.relpath(root, publish_path) - links[path] = ('%s\n' % - (path, path)) - - if os.path.isfile(os.path.join(root, 'api-ref.html')): - path = os.path.relpath(root, publish_path) - links[path] = ('%s\n' % - (path, path)) - - # List PDF files for api-site that have from "bk-api-ref*.pdf" - # as well since they have no corresponding html file. - for f in files: - if f.startswith('bk-api-ref') and f.endswith('.pdf'): - path = os.path.relpath(root, publish_path) - links[f] = ('%s\n' % - (path, f, f)) - - for entry in sorted(links): - index_file.write(links[entry]) - index_file.write('
\n') - - if os.path.isfile(os.path.join(get_publish_path(), 'www-index.html')): - index_file.write('
\n') - index_file.write('list of generated ' - 'WWW pages\n') - index_file.write('\n' - '\n') - index_file.close() - - def build_affected_books(rootdir, book_exceptions, file_exceptions, force=False, ignore_dirs=None, ignore_books=None): @@ -1379,7 +1319,7 @@ def build_affected_books(rootdir, book_exceptions, file_exceptions, any_failures = True if cfg.CONF.create_index: - generate_index_file() + index.generate_index_file(get_publish_path()) if any_failures: for book, result, output, returncode in RESULTS_OF_BUILDS: @@ -1633,7 +1573,7 @@ def doctest(): if check_no_building(): if CONF.create_index: - generate_index_file() + index.generate_index_file(get_publish_path()) return if CONF.check_syntax or CONF.check_niceness or CONF.check_links: diff --git a/os_doc_tools/index.py b/os_doc_tools/index.py new file mode 100644 index 00000000..4e0efdb0 --- /dev/null +++ b/os_doc_tools/index.py @@ -0,0 +1,96 @@ +#!/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 os +import sys + + +def generate_index_file(publish_path): + """Generate index.html file in publish_path.""" + + if not os.path.isdir(publish_path): + os.mkdir(publish_path) + + index_file = open(os.path.join(publish_path, 'index.html'), 'w') + + index_file.write( + '\n' + '\n' + '\n' + '

Generated documents

\n') + + links = {} + for root, dirs, files in os.walk(publish_path): + + dirs[:] = [d for d in dirs if d not in ['common', 'webapp', 'content', + 'www']] + + # Ignore top-level index.html files + if root == publish_path: + continue + + if os.path.isfile(os.path.join(root, 'content/index.html')): + path = os.path.relpath(root, publish_path) + links[path] = ('%s\n' % + (path, path)) + elif os.path.isfile(os.path.join(root, 'index.html')): + path = os.path.relpath(root, publish_path) + links[path] = ('%s\n' % + (path, path.replace('draft/', ''))) + + if os.path.isfile(os.path.join(root, 'api-ref.html')): + path = os.path.relpath(root, publish_path) + links[path] = ('%s\n' % + (path, path)) + + # List PDF files for api-site that have from "bk-api-ref*.pdf" + # as well since they have no corresponding html file. + for f in files: + if f.startswith('bk-api-ref') and f.endswith('.pdf'): + path = os.path.relpath(root, publish_path) + links[f] = ('%s\n' % + (path, f, f)) + + for entry in sorted([s for s in links if not s.startswith('draft/')]): + index_file.write(links[entry]) + index_file.write('
\n') + + drafts = [s for s in links if s.startswith('draft/')] + if drafts: + index_file.write('

Draft guides

\n') + for entry in sorted(drafts): + index_file.write(links[entry]) + index_file.write('
\n') + + if os.path.isfile(os.path.join(publish_path, 'www-index.html')): + index_file.write('

WWW index pages

\n') + index_file.write('List of generated ' + 'WWW pages\n') + index_file.write('\n' + '\n') + index_file.close() + + +def main(): + parser = argparse.ArgumentParser(description="Generate index file.") + parser.add_argument('directory', metavar='DIR', + help="Directory to search.") + args = parser.parse_args() + + generate_index_file(args.directory) + +if __name__ == "__main__": + sys.exit(main()) diff --git a/releasenotes/notes/separate-index-cce0ae4286f1da53.yaml b/releasenotes/notes/separate-index-cce0ae4286f1da53.yaml new file mode 100644 index 00000000..1f402eca --- /dev/null +++ b/releasenotes/notes/separate-index-cce0ae4286f1da53.yaml @@ -0,0 +1,4 @@ +--- +features: + - New command ``openstack-indexpage`` to only generate the HTML + index page. The index page layout has also been improved. diff --git a/setup.cfg b/setup.cfg index 3e72b2dd..63a3b1da 100644 --- a/setup.cfg +++ b/setup.cfg @@ -42,6 +42,7 @@ console_scripts = openstack-generate-docbook = os_doc_tools.handle_pot:generatedocbook openstack-generate-pot = os_doc_tools.handle_pot:generatepot openstack-jsoncheck = os_doc_tools.jsoncheck:main + openstack-indexpage = os_doc_tools.index:main [build_sphinx] source-dir = doc/source