diff --git a/.gitignore b/.gitignore index 8415248..f68a32c 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,6 @@ bin # Node modules web/node_modules + +# Sphinx build venv +.tox/ diff --git a/.zuul.yaml b/.zuul.yaml index 243bf03..1abff94 100644 --- a/.zuul.yaml +++ b/.zuul.yaml @@ -11,17 +11,24 @@ # limitations under the License. - project: + vars: + sphinx_build_dir: docs/build check: jobs: + - openstack-tox-docs - airshipui-test - airshipui-lint gate: jobs: + - openstack-tox-docs - airshipui-test - airshipui-lint post: jobs: - airshipui-upload-git-mirror + promote: + jobs: + - promote-airship-project-docs - job: name: airshipui-test diff --git a/Makefile b/Makefile index 11ba71d..a7cdf66 100644 --- a/Makefile +++ b/Makefile @@ -53,6 +53,10 @@ cover: test clean: rm -rf $(BUILD_DIR) $(COVERAGE_OUTPUT) +.PHONY: docs +docs: + tox + # The golang-unit zuul job calls the env target, so create one # Note: on windows if there is a WSL curl in c:\windows\system32 # it will cause problems installing the lint tools. diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..02465b2 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,3 @@ +# Sphinx build folders +build/ +_build/ \ No newline at end of file diff --git a/docs/img/airship.logo.white.svg b/docs/img/airship.logo.white.svg new file mode 100644 index 0000000..b664296 --- /dev/null +++ b/docs/img/airship.logo.white.svg @@ -0,0 +1 @@ +logo_white \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..6a60395 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,17 @@ +# The order of packages is significant, because pip processes them in the order +# of appearance. Changing the order has an impact on the overall integration +# process, which may cause wedges in the gate later. + +# Documentation +sphinx>2.1.0 +oslosphinx>=4.7.0 # Apache-2.0 +sphinx_rtd_theme + +# UML image generation +plantuml + +# Releasenotes +reno>=2.5.0 # Apache-2.0 + +# Sphinx markdown extension +recommonmark diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..83d52da --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,66 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) +import sphinx_rtd_theme + + +# -- Project information ----------------------------------------------------- + +project = 'airshipui' +copyright = '2020, The Airship Authors' +author = 'The Airship Authors' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'recommonmark' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_logo = "img/airship.logo.white.svg" +html_theme = "sphinx_rtd_theme" +html_theme_options = { + 'display_version': False, + 'logo_only': True +} +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Source files +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} diff --git a/DevelopersGuide.md b/docs/source/developers.md similarity index 100% rename from DevelopersGuide.md rename to docs/source/developers.md diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..fe9a6d8 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,24 @@ +.. + Copyright 2018 AT&T Intellectual Property. + All 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. + +===================================== +Welcome to airshipui's Documentation! +===================================== + +.. toctree:: + :maxdepth: 2 + + developers diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..8c7e6d0 --- /dev/null +++ b/tox.ini @@ -0,0 +1,19 @@ +[tox] +envlist = docs +skipsdist = true + +[testenv] +setenv = VIRTUAL_ENV={envdir} + LANGUAGE=en_US + LC_ALL=en_US.utf-8 +passenv = http_proxy HTTP_PROXY https_proxy HTTPS_PROXY no_proxy NO_PROXY + +[testenv:docs] +basepython = python3 +whitelist_externals = rm +deps = + -r{toxinidir}/docs/requirements.txt +commands = + rm -rf docs/build + sphinx-build docs/source docs/build/html +