From 7c90da14b4b3f48f953c411d93421d570577a628 Mon Sep 17 00:00:00 2001 From: Scott Hussey Date: Mon, 30 Jul 2018 14:41:59 -0500 Subject: [PATCH] docs: Add doc building jobs and doc index page with link * Rename docs => doc for OpenStack convention compliance * Add tox.ini job for docs building (no setup.py required) * Add Makefile with docs entrypoint * Add a link to the airship-specs subproject. Change-Id: I835633405b3dac671aa123eb4ee04645f390c352 --- .gitignore | 6 +++--- Makefile | 17 +++++++++++++++++ {docs => doc}/requirements.txt | 0 {docs => doc}/source/alarming-conditions.rst | 0 {docs => doc}/source/api-conventions.rst | 0 {docs => doc}/source/client-software.rst | 0 {docs => doc}/source/code-conventions.rst | 0 {docs => doc}/source/conf.py | 0 {docs => doc}/source/conventions.rst | 0 {docs => doc}/source/dev-getting-started.rst | 0 .../source/documentation-conventions.rst | 0 {docs => doc}/source/docutils.conf | 0 {docs => doc}/source/index.rst | 8 ++++++++ {docs => doc}/source/rbac-conventions.rst | 0 {docs => doc}/source/security-conventions.rst | 0 .../source/service-logging-conventions.rst | 0 {docs => doc}/source/ucp-basic-deployment.rst | 0 tox.ini | 19 +++++++++++++++++++ 18 files changed, 47 insertions(+), 3 deletions(-) create mode 100644 Makefile rename {docs => doc}/requirements.txt (100%) rename {docs => doc}/source/alarming-conditions.rst (100%) rename {docs => doc}/source/api-conventions.rst (100%) rename {docs => doc}/source/client-software.rst (100%) rename {docs => doc}/source/code-conventions.rst (100%) rename {docs => doc}/source/conf.py (100%) rename {docs => doc}/source/conventions.rst (100%) rename {docs => doc}/source/dev-getting-started.rst (100%) rename {docs => doc}/source/documentation-conventions.rst (100%) rename {docs => doc}/source/docutils.conf (100%) rename {docs => doc}/source/index.rst (91%) rename {docs => doc}/source/rbac-conventions.rst (100%) rename {docs => doc}/source/security-conventions.rst (100%) rename {docs => doc}/source/service-logging-conventions.rst (100%) rename {docs => doc}/source/ucp-basic-deployment.rst (100%) create mode 100644 tox.ini diff --git a/.gitignore b/.gitignore index c582ac25..a9ed3823 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,6 @@ # Sphinx documentation -docs/_build/ -docs/build/ +doc/_build/ +doc/build/ # OSX folder settings files -.DS_Store \ No newline at end of file +.DS_Store diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..984020f1 --- /dev/null +++ b/Makefile @@ -0,0 +1,17 @@ +# Copyright 2017 AT&T Intellectual Property. All other rights reserved. +# +# 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. + +.PHONY: docs +docs: + tox -e docs diff --git a/docs/requirements.txt b/doc/requirements.txt similarity index 100% rename from docs/requirements.txt rename to doc/requirements.txt diff --git a/docs/source/alarming-conditions.rst b/doc/source/alarming-conditions.rst similarity index 100% rename from docs/source/alarming-conditions.rst rename to doc/source/alarming-conditions.rst diff --git a/docs/source/api-conventions.rst b/doc/source/api-conventions.rst similarity index 100% rename from docs/source/api-conventions.rst rename to doc/source/api-conventions.rst diff --git a/docs/source/client-software.rst b/doc/source/client-software.rst similarity index 100% rename from docs/source/client-software.rst rename to doc/source/client-software.rst diff --git a/docs/source/code-conventions.rst b/doc/source/code-conventions.rst similarity index 100% rename from docs/source/code-conventions.rst rename to doc/source/code-conventions.rst diff --git a/docs/source/conf.py b/doc/source/conf.py similarity index 100% rename from docs/source/conf.py rename to doc/source/conf.py diff --git a/docs/source/conventions.rst b/doc/source/conventions.rst similarity index 100% rename from docs/source/conventions.rst rename to doc/source/conventions.rst diff --git a/docs/source/dev-getting-started.rst b/doc/source/dev-getting-started.rst similarity index 100% rename from docs/source/dev-getting-started.rst rename to doc/source/dev-getting-started.rst diff --git a/docs/source/documentation-conventions.rst b/doc/source/documentation-conventions.rst similarity index 100% rename from docs/source/documentation-conventions.rst rename to doc/source/documentation-conventions.rst diff --git a/docs/source/docutils.conf b/doc/source/docutils.conf similarity index 100% rename from docs/source/docutils.conf rename to doc/source/docutils.conf diff --git a/docs/source/index.rst b/doc/source/index.rst similarity index 91% rename from docs/source/index.rst rename to doc/source/index.rst index 4ae4c8e8..479258ea 100644 --- a/docs/source/index.rst +++ b/doc/source/index.rst @@ -45,6 +45,12 @@ Use of ``sphinx-build -b html docs/source docs/build`` will build a html version of this documentation that can be viewed using a browser at docs/build/index.html on the local filesystem. +Specification Details +--------------------- + +Proposed, approved, and implemented specifications_ for +Airship projects are available. + Conventions and Standards ------------------------- @@ -53,6 +59,7 @@ Conventions and Standards conventions dev-getting-started + ucp-basic-deployment .. _airshipit.org: https://airshipit.org @@ -62,3 +69,4 @@ Conventions and Standards .. _Openstack-Helm: https://docs.openstack.org/openstack-helm/latest/ .. _Treasuremap: https://github.com/att-comdev/treasuremap .. _yaml: http://yaml.org/ +.. _specifications: /projects/specs diff --git a/docs/source/rbac-conventions.rst b/doc/source/rbac-conventions.rst similarity index 100% rename from docs/source/rbac-conventions.rst rename to doc/source/rbac-conventions.rst diff --git a/docs/source/security-conventions.rst b/doc/source/security-conventions.rst similarity index 100% rename from docs/source/security-conventions.rst rename to doc/source/security-conventions.rst diff --git a/docs/source/service-logging-conventions.rst b/doc/source/service-logging-conventions.rst similarity index 100% rename from docs/source/service-logging-conventions.rst rename to doc/source/service-logging-conventions.rst diff --git a/docs/source/ucp-basic-deployment.rst b/doc/source/ucp-basic-deployment.rst similarity index 100% rename from docs/source/ucp-basic-deployment.rst rename to doc/source/ucp-basic-deployment.rst diff --git a/tox.ini b/tox.ini new file mode 100644 index 00000000..41951a31 --- /dev/null +++ b/tox.ini @@ -0,0 +1,19 @@ +[tox] +# Allows docs to be built without setup.py having to exist. Requires that +# usedevelop be False as well (which it is by default). +skipsdist = True +envlist = docs + +[testenv] +passenv=HTTP_PROXY HTTPS_PROXY http_proxy https_proxy NO_PROXY no_proxy +setenv= + VIRTUAL_ENV={envdir} +install_command = pip install {opts} {packages} + +[testenv:docs] +basepython = python3 +deps = -r{toxinidir}/doc/requirements.txt +commands = + rm -rf doc/build + sphinx-build -W -b html doc/source doc/build/html +whitelist_externals = rm