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:
parent
b43e4e4fea
commit
b8a2bb3b27
3
.gitignore
vendored
3
.gitignore
vendored
@ -19,3 +19,6 @@ bin/
|
|||||||
.vimrc
|
.vimrc
|
||||||
*.swp
|
*.swp
|
||||||
.vscode/
|
.vscode/
|
||||||
|
|
||||||
|
# Sphinx build venv
|
||||||
|
venv/
|
||||||
|
@ -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).
|
43
Makefile
43
Makefile
@ -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):
|
||||||
|
@ -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
3
docs/.gitignore
vendored
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
# Sphinx build folders
|
||||||
|
build/
|
||||||
|
_build/
|
17
docs/requirements.txt
Normal file
17
docs/requirements.txt
Normal 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
61
docs/source/conf.py
Normal 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',
|
||||||
|
}
|
@ -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
|
||||||
|
|
Before Width: | Height: | Size: 339 KiB After Width: | Height: | Size: 339 KiB |
26
docs/source/index.rst
Normal file
26
docs/source/index.rst
Normal 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
|
@ -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.
|
Loading…
Reference in New Issue
Block a user