From b8a2bb3b27e240da15aeb24ce118ae52d0824a89 Mon Sep 17 00:00:00 2001 From: "Ian H. Pittwood" Date: Wed, 8 Jan 2020 09:45:02 -0600 Subject: [PATCH] Updates to Makefile Implements `make docs` command to create rtd-themed docs using Sphinx from the existing Markdown documents in the docs directory. Changes the `get-modules` command to `depend` to more closely match OpenStack guidelines in [0]. Adds `fmt` command as specified in [0], currently referencing the `lint` command. Adds `godoc` command that will host a local godoc server instance with a link directly to airshipctl technical documentation. Adds `releasenotes` commands specified in [0], currently noted as "TODO". Adds `images` command as found in other Airship projects, referencing `docker-image`. [0] https://governance.openstack.org/tc/reference/pti/golang.html Change-Id: I134fc2c2714bce6d23dc9cf8b86c3016d68def7e --- .gitignore | 3 ++ CONTRIBUTING.md | 2 +- Makefile | 43 +++++++++++++++-- README.md | 4 +- docs/.gitignore | 3 ++ docs/requirements.txt | 17 +++++++ docs/source/conf.py | 61 ++++++++++++++++++++++++ docs/{ => source}/developers.md | 2 +- docs/{ => source}/img/architecture.png | Bin docs/source/index.rst | 26 ++++++++++ docs/{ => source}/plugins.md | 2 +- docs/{ => source}/testing-guidelines.md | 0 12 files changed, 155 insertions(+), 8 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/requirements.txt create mode 100644 docs/source/conf.py rename docs/{ => source}/developers.md (99%) rename docs/{ => source}/img/architecture.png (100%) create mode 100644 docs/source/index.rst rename docs/{ => source}/plugins.md (98%) rename docs/{ => source}/testing-guidelines.md (100%) diff --git a/.gitignore b/.gitignore index 6bac1bb29..efe3b790b 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,6 @@ bin/ .vimrc *.swp .vscode/ + +# Sphinx build venv +venv/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 52bdd48e1..5d09036bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,4 +39,4 @@ chronologically ordering work in Jira. Airship has a set of [coding conventions](https://airship-docs.readthedocs.io/en/latest/conventions.html) that are meant to cover all Airship subprojects. -However, airshipctl also has its own specific coding conventions and standards in the official airshipctl [developer guide](docs/developers.md). \ No newline at end of file +However, airshipctl also has its own specific coding conventions and standards in the official airshipctl [developer guide](docs/source/developers.md). \ No newline at end of file diff --git a/Makefile b/Makefile index ea7fe9147..44c90cdf8 100644 --- a/Makefile +++ b/Makefile @@ -33,14 +33,30 @@ PROXY ?= http://proxy.foo.com:8000 NO_PROXY ?= localhost,127.0.0.1,.svc.cluster.local USE_PROXY ?= false -.PHONY: get-modules -get-modules: +# Sphinx document options +PYTHON_EXECUTABLE := python +SPHINXBUILD ?= sphinx-build +SOURCEDIR = docs/source +BUILDDIR = docs/build +REQUIREMENTSTXT := docs/requirements.txt + +# Godoc server options +GD_GOROOT ?= /usr/lib/go # Godoc has trouble with symbolic links, some may need to use /usr/share/go +GD_PORT ?= 8080 + +.PHONY: depend +depend: @go mod download .PHONY: build -build: get-modules +build: depend @CGO_ENABLED=0 go build -o $(BINDIR)/$(EXECUTABLE_CLI) $(GO_FLAGS) +.PHONY: install +install: depend +install: + @CGO_ENABLED=0 go install . + .PHONY: test test: lint test: cover @@ -57,6 +73,9 @@ cover: COVER_FLAGS = -covermode=atomic -coverprofile=$(COVER_PROFILE) cover: unit-tests @./tools/coverage_check $(COVER_PROFILE) +.PHONY: fmt +fmt: lint + .PHONY: lint lint: tidy lint: $(LINTER) @@ -70,6 +89,9 @@ tidy: @./tools/gomod_check @echo "go.mod is up to date" +.PHONY: images +images: docker-image + .PHONY: docker-image docker-image: ifeq ($(USE_PROXY), true) @@ -112,6 +134,21 @@ clean: .PHONY: docs docs: + @$(PYTHON_EXECUTABLE) -m venv venv + source ./venv/bin/activate + @$(PYTHON_EXECUTABLE) -m pip install -r ${REQUIREMENTSTXT} + @$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" + rm -rf venv + +.PHONY: godoc +godoc: + @go get golang.org/x/tools + @go install golang.org/x/tools/cmd/godoc + @echo "Follow this link to package documentation: http://localhost:${GD_PORT}/pkg/opendev.org/airship/airshipctl/" + @godoc -http=":${GD_PORT}" -goroot ${GD_GOROOT} + +.PHONY: releasenotes +releasenotes: @echo "TODO" $(TOOLBINDIR): diff --git a/README.md b/README.md index 509a176eb..950d1e6d2 100644 --- a/README.md +++ b/README.md @@ -27,14 +27,14 @@ Blog Series](https://www.airshipit.org/blog/). This project is under heavy active development to reach an alpha state. New developers should read the [contributing guide](CONTRIBUTING.md) as -well as the [developer guide](docs/developers.md) in order to get started. +well as the [developer guide](docs/source/developers.md) in order to get started. ## Architecture The `airshipctl` tool is designed to work against declarative infrastructure housed in source control and manage the lifecycle of a site. -![architecture diagram](docs/img/architecture.png) +![architecture diagram](docs/source/img/architecture.png) ## Example Usage diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..02465b28a --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,3 @@ +# Sphinx build folders +build/ +_build/ \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..7a789d9d8 --- /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 000000000..15489a4c6 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,61 @@ +# 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 = 'airshipctl' +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_theme = "sphinx_rtd_theme" +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', +} \ No newline at end of file diff --git a/docs/developers.md b/docs/source/developers.md similarity index 99% rename from docs/developers.md rename to docs/source/developers.md index 5bb196292..2c6aee8df 100644 --- a/docs/developers.md +++ b/docs/source/developers.md @@ -45,7 +45,7 @@ is not to burden contributors, but to build elegant and high-quality open source code so that our users will benefit. Make sure you have read and understood the main airshipctl [Contributing -Guide](../CONTRIBUTING.md) +Guide](../../CONTRIBUTING.md) ### Structure of the Code diff --git a/docs/img/architecture.png b/docs/source/img/architecture.png similarity index 100% rename from docs/img/architecture.png rename to docs/source/img/architecture.png diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 000000000..2e0adf398 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,26 @@ +.. + 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. + +======================== +airshipctl Documentation +======================== + +.. toctree:: + :maxdepth: 2 + + developers + plugins + testing-guidelines \ No newline at end of file diff --git a/docs/plugins.md b/docs/source/plugins.md similarity index 98% rename from docs/plugins.md rename to docs/source/plugins.md index 540050692..62051bf72 100644 --- a/docs/plugins.md +++ b/docs/source/plugins.md @@ -224,4 +224,4 @@ func main() { ``` The `AirshipCTLSettings` object can be found -[here](pkg/environment/settings.go). Future documentation TBD. +[here](../../pkg/environment/settings.go). Future documentation TBD. diff --git a/docs/testing-guidelines.md b/docs/source/testing-guidelines.md similarity index 100% rename from docs/testing-guidelines.md rename to docs/source/testing-guidelines.md