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
This commit is contained in:
Ian H. Pittwood 2020-01-08 09:45:02 -06:00
parent b43e4e4fea
commit b8a2bb3b27
12 changed files with 155 additions and 8 deletions

3
.gitignore vendored
View File

@ -19,3 +19,6 @@ bin/
.vimrc .vimrc
*.swp *.swp
.vscode/ .vscode/
# Sphinx build venv
venv/

View File

@ -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. 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). However, airshipctl also has its own specific coding conventions and standards in the official airshipctl [developer guide](docs/source/developers.md).

View File

@ -33,14 +33,30 @@ PROXY ?= http://proxy.foo.com:8000
NO_PROXY ?= localhost,127.0.0.1,.svc.cluster.local NO_PROXY ?= localhost,127.0.0.1,.svc.cluster.local
USE_PROXY ?= false USE_PROXY ?= false
.PHONY: get-modules # Sphinx document options
get-modules: 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 @go mod download
.PHONY: build .PHONY: build
build: get-modules build: depend
@CGO_ENABLED=0 go build -o $(BINDIR)/$(EXECUTABLE_CLI) $(GO_FLAGS) @CGO_ENABLED=0 go build -o $(BINDIR)/$(EXECUTABLE_CLI) $(GO_FLAGS)
.PHONY: install
install: depend
install:
@CGO_ENABLED=0 go install .
.PHONY: test .PHONY: test
test: lint test: lint
test: cover test: cover
@ -57,6 +73,9 @@ cover: COVER_FLAGS = -covermode=atomic -coverprofile=$(COVER_PROFILE)
cover: unit-tests cover: unit-tests
@./tools/coverage_check $(COVER_PROFILE) @./tools/coverage_check $(COVER_PROFILE)
.PHONY: fmt
fmt: lint
.PHONY: lint .PHONY: lint
lint: tidy lint: tidy
lint: $(LINTER) lint: $(LINTER)
@ -70,6 +89,9 @@ tidy:
@./tools/gomod_check @./tools/gomod_check
@echo "go.mod is up to date" @echo "go.mod is up to date"
.PHONY: images
images: docker-image
.PHONY: docker-image .PHONY: docker-image
docker-image: docker-image:
ifeq ($(USE_PROXY), true) ifeq ($(USE_PROXY), true)
@ -112,6 +134,21 @@ clean:
.PHONY: docs .PHONY: docs
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" @echo "TODO"
$(TOOLBINDIR): $(TOOLBINDIR):

View File

@ -27,14 +27,14 @@ Blog Series](https://www.airshipit.org/blog/).
This project is under heavy active development to reach an alpha state. This project is under heavy active development to reach an alpha state.
New developers should read the [contributing guide](CONTRIBUTING.md) as 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 ## Architecture
The `airshipctl` tool is designed to work against declarative infrastructure The `airshipctl` tool is designed to work against declarative infrastructure
housed in source control and manage the lifecycle of a site. 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 ## Example Usage

3
docs/.gitignore vendored Normal file
View File

@ -0,0 +1,3 @@
# Sphinx build folders
build/
_build/

17
docs/requirements.txt Normal file
View File

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

61
docs/source/conf.py Normal file
View File

@ -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',
}

View File

@ -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. code so that our users will benefit.
Make sure you have read and understood the main airshipctl [Contributing Make sure you have read and understood the main airshipctl [Contributing
Guide](../CONTRIBUTING.md) Guide](../../CONTRIBUTING.md)
### Structure of the Code ### Structure of the Code

View File

Before

Width:  |  Height:  |  Size: 339 KiB

After

Width:  |  Height:  |  Size: 339 KiB

26
docs/source/index.rst Normal file
View File

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

View File

@ -224,4 +224,4 @@ func main() {
``` ```
The `AirshipCTLSettings` object can be found The `AirshipCTLSettings` object can be found
[here](pkg/environment/settings.go). Future documentation TBD. [here](../../pkg/environment/settings.go). Future documentation TBD.