Browse Source

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
changes/88/248388/2
Andreas Jaeger 5 years ago
parent
commit
39b5ecfbd9
4 changed files with 104 additions and 63 deletions
  1. +3
    -63
      os_doc_tools/doctest.py
  2. +96
    -0
      os_doc_tools/index.py
  3. +4
    -0
      releasenotes/notes/separate-index-cce0ae4286f1da53.yaml
  4. +1
    -0
      setup.cfg

+ 3
- 63
os_doc_tools/doctest.py View File

@ -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(
'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"\n'
'"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">\n'
'<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\n'
'<body>\n'
'<h1>Results of checkbuild</h1>\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] = ('<a href="%s/content/index.html">%s</a>\n' %
(path, path))
elif os.path.isfile(os.path.join(root, 'index.html')):
path = os.path.relpath(root, publish_path)
links[path] = ('<a href="%s/index.html">%s</a>\n' %
(path, path))
if os.path.isfile(os.path.join(root, 'api-ref.html')):
path = os.path.relpath(root, publish_path)
links[path] = ('<a href="%s/api-ref.html">%s</a>\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] = ('<a href="%s/%s">%s</a>\n' %
(path, f, f))
for entry in sorted(links):
index_file.write(links[entry])
index_file.write('<br/>\n')
if os.path.isfile(os.path.join(get_publish_path(), 'www-index.html')):
index_file.write('<br/>\n')
index_file.write('<a href="www-index.html">list of generated '
'WWW pages</a>\n')
index_file.write('</body>\n'
'</html>\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:


+ 96
- 0
os_doc_tools/index.py View File

@ -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(
'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"\n'
'"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">\n'
'<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\n'
'<body>\n'
'<h1>Generated documents</h1>\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] = ('<a href="%s/content/index.html">%s</a>\n' %
(path, path))
elif os.path.isfile(os.path.join(root, 'index.html')):
path = os.path.relpath(root, publish_path)
links[path] = ('<a href="%s/index.html">%s</a>\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] = ('<a href="%s/api-ref.html">%s</a>\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] = ('<a href="%s/%s">%s</a>\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('<br/>\n')
drafts = [s for s in links if s.startswith('draft/')]
if drafts:
index_file.write('<h2>Draft guides</h2>\n')
for entry in sorted(drafts):
index_file.write(links[entry])
index_file.write('<br/>\n')
if os.path.isfile(os.path.join(publish_path, 'www-index.html')):
index_file.write('<h2>WWW index pages</h2>\n')
index_file.write('<a href="www-index.html">List of generated '
'WWW pages</a>\n')
index_file.write('</body>\n'
'</html>\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())

+ 4
- 0
releasenotes/notes/separate-index-cce0ae4286f1da53.yaml View File

@ -0,0 +1,4 @@
---
features:
- New command ``openstack-indexpage`` to only generate the HTML
index page. The index page layout has also been improved.

+ 1
- 0
setup.cfg View File

@ -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


Loading…
Cancel
Save