openstack/api-site
Code Issues Proposed changes

Drop DocBook support, swagger building

Browse Source 
We do not need to build and publish the DocBook XML content anymore,
everything is frozen and in the process of moving to projects. Remove
set up for building of DocBook content.

This leaves the XML files still in tree, we can remove them later.

The DocBook XML gates are still setup, so some tox environments have
been made a noop.

Require openstack-doc-tools 1.0.0 which removes DocBook XML support.

Also, drop swagger building, this is not needed anymore.

Change-Id: I276953013a518a09dabb89bb8f80ef7739b4491b
This commit is contained in:
Andreas Jaeger 2016-08-22 17:49:55 +02:00
parent 6fde831f54
commit bb8b09bd7a
8 changed files with 16 additions and 113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.rst
View File

@ -81,8 +81,6 @@ install the Python tox package and run ``tox`` from the top-level directory.
To run individual tests:
* ``tox -e checkniceness`` - Niceness tests
* ``tox -e checksyntax`` - Syntax checks
* ``tox -e checkdeletions`` - Verifies that no deleted files are referenced
* ``tox -e checkbuild`` - Builds all of the documents in this repository
To run these tests, the Tox package uses the

5
bindep.txt
View File

@ -1,10 +1,7 @@
# This is a cross-platform list tracking distribution packages needed by tests;
# see http://docs.openstack.org/infra/bindep/ for additional information.
fonts-nanum [platform:dpkg]
fonts-takao [platform:dpkg]
gettext
gnome-doc-utils
graphviz
libjpeg-dev [platform:dpkg]
libjpeg-turbo-devel [platform:rpm]
@ -14,7 +11,5 @@ libxml2-utils [platform:dpkg]
libxslt-devel [platform:rpm]
libxslt1-dev [platform:dpkg]
python-dev [platform:dpkg]
python-lxml
xsltproc [platform:dpkg]
zlib-devel [platform:rpm]
zlib1g-dev [platform:dpkg]

5
doc-tools-check-languages.conf
View File

@ -37,7 +37,7 @@ declare -A DRAFTS=(
# Where does the top-level pom live?
# Set to empty to not copy it.
POM_FILE="pom.xml"
POM_FILE=""
# Location of doc dir
DOC_DIR="./"
@ -50,4 +50,7 @@ SPECIAL_BOOKS=(
["firstapp"]="RST"
# These are translated in openstack-manuals
["common"]="skip"
# Frozen
["api-ref"]="skip"
["api-ref-guides"]="skip"
)

44
pom.xml
View File

@ -1,44 +0,0 @@
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.openstack.docs</groupId>
<artifactId>parent-pom</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<modules>
<module>api-ref</module>
<module>api-ref-guides</module>
</modules>
<profiles>
<profile>
<id>Rackspace Research Repositories</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<repositories>
<repository>
<id>rackspace-research</id>
<name>Rackspace Research Repository</name>
<url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>rackspace-research</id>
<name>Rackspace Research Repository</name>
<url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
</pluginRepository>
</pluginRepositories>
</profile>
</profiles>
<build>
<plugins>
<plugin>
<groupId>com.rackspace.cloud.api</groupId>
<artifactId>clouddocs-maven-plugin</artifactId>
<version>2.1.4</version>
</plugin>
</plugins>
</build>
</project>

3
test-requirements.txt
View File

@ -2,7 +2,7 @@
# of appearance. Changing the order has an impact on the overall integration
# process, which may cause wedges in the gate later.
pbr>=1.6
openstack-doc-tools>=0.30
openstack-doc-tools>=1.0.0
doc8 # Apache-2.0
Pygments
# At least 1.3 is required for dedent in code blocks. Capped to 1.3 to not get an automatic update to any newer versions.
@ -10,4 +10,3 @@ sphinx>=1.3,!=1.3b1,<1.4
openstackdocstheme>=1.4.0
nwdiag
sphinxcontrib-nwdiag
fairy-slipper

38
tools/build-api-ref-swagger.sh
View File

@ -1,38 +0,0 @@
#!/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.
# fairy-slipper should be installed with test-requirements.txt
# Migrate DocBook and WADL files to Swagger JSON
function convert_to_swagger {
if [ ! -d swagger ]; then
mkdir swagger
fi
# Generate JSON
find api-ref/src/docbkx/ -name api-ref-\* -type f -exec fairy-slipper-docbkx-to-json -o swagger {} \;
# Generate Swagger
for file in swagger/*.json
do
echo $file
fairy-slipper-wadl-to-swagger-valid $file -o swagger
done
# Remove interim JSON files
rm -r swagger/api-ref*
}
convert_to_swagger

2
tools/build-index.sh
View File

@ -30,6 +30,8 @@ if [ "$PUBLISH" = "build" ] ; then
# 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
# Create index page for viewing
openstack-indexpage publish-docs
fi
if [ "$PUBLISH" = "publish" ] ; then

30
tox.ini
View File

@ -1,6 +1,6 @@
[tox]
minversion = 1.6
envlist = checkniceness,checksyntax,checkdeletions,checkbuild,checklinks
envlist = checkniceness,checkbuild
skipsdist = True
[testenv]
@ -18,25 +18,21 @@ whitelist_externals =
commands = {posargs}
[testenv:checklinks]
commands = openstack-doc-test --check-links {posargs}
# TODO(jaegerandi): Remove environment once infra build jobs are stopped.
commands = true
[testenv:checkniceness]
commands =
openstack-doc-test --check-niceness {posargs}
doc8 firstapp
doc8 api-quick-start
[testenv:checksyntax]
commands =
# WADLs using entity files are not properly handled by
# openstack-doc-test, we therefore have to check all files that
# are in the tree for any syntax issues.
openstack-doc-test --check-syntax --force {posargs}
# Check that .po and .pot files are valid:
bash -c "find api* -type f -regex '.*\.pot?' -print0|xargs -0 -n 1 msgfmt --check-format -o /dev/null"
# TODO(jaegerandi): Remove environment once infra build jobs are stopped.
commands = true
[testenv:checkdeletions]
commands = openstack-doc-test --check-deletions {posargs}
# TODO(jaegerandi): Remove environment once infra build jobs are stopped.
commands = true
[testenv:checkbuild]
commands =
@ -44,13 +40,10 @@ commands =
{toxinidir}/tools/build-all-rst.sh
# Build website index
{toxinidir}/tools/build-index.sh build
# Build DocBook Guides
openstack-doc-test --check-build {posargs}
[testenv:makeswagger]
commands =
# Build Swagger files
{toxinidir}/tools/build-api-ref-swagger.sh
# TODO(jaegerandi): Remove environment once infra build jobs are stopped.
commands = true
[testenv:publishdocs]
# Prepare documents (without www) so that they can get published on
@ -61,17 +54,12 @@ commands = true
# Prepare documents (without www) so that they can get published on
# developer.openstack.org with just copying publish-docs/api-ref over.
commands =
openstack-doc-test --check-build --publish --only-book api-ref --only-book api-ref-guides
# We need to move api-ref-guides to the proper place:
mv publish-docs/api-ref-guides publish-docs/api-ref/
# Build and copy RST Guides
{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
# Build RST/JSON from fairy-slipper
{toxinidir}/tools/build-api-ref-swagger.sh
[testenv:checklang]
# openstack-generate-docbook needs xml2po which cannot be installed in