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

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

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

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):

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
 

docs/.gitignore

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

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

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

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
 

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

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.