You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficcontrol.apache.org by sh...@apache.org on 2021/10/27 22:42:10 UTC
[trafficcontrol] branch master updated: Add T3C README-based docs
to the documentation build (#6158)
This is an automated email from the ASF dual-hosted git repository.
shamrick pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficcontrol.git
The following commit(s) were added to refs/heads/master by this push:
new 3255a0e Add T3C README-based docs to the documentation build (#6158)
3255a0e is described below
commit 3255a0e728ee0a713c53747eb320ee326034679d
Author: ocket8888 <oc...@apache.org>
AuthorDate: Wed Oct 27 16:42:00 2021 -0600
Add T3C README-based docs to the documentation build (#6158)
* Add license header to README
* Add planned output files to .gitignore
* Add Makefile for t3c docs
* Add Makefile usage to README
* Add T3C docs to documentation builds
* Add .gitignore for built t3c docs
* Add new dependency to docs build systems
* Try a workaround for ammaraskar/sphinx-action#33
* Fix pkg build for docs
* fix missing argument definition
---
.github/workflows/docs.yml | 1 +
cache-config/.gitignore | 4 ++
cache-config/Makefile | 62 ++++++++++++++++++++++
cache-config/README.md | 26 +++++++++
docs/Makefile | 57 ++++++++++++--------
docs/source/admin/index.rst | 1 +
{cache-config => docs/source/admin/t3c}/.gitignore | 14 ++---
docs/source/admin/t3c/index.rst | 29 ++++++++++
docs/source/admin/traffic_server.rst | 4 +-
docs/source/glossary.rst | 2 +
infrastructure/docker/build/Dockerfile-docs | 7 +++
11 files changed, 172 insertions(+), 35 deletions(-)
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index c29fcbb..eb162e8 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -48,6 +48,7 @@ jobs:
uses: ./.github/actions/sphinx-action
with:
docs-folder: "docs/"
+ pre-build-command: "apt-get install -y pandoc"
- uses: actions/upload-artifact@v1
with:
name: HTMLDocumentation
diff --git a/cache-config/.gitignore b/cache-config/.gitignore
index 88bf146..94cb8c8 100644
--- a/cache-config/.gitignore
+++ b/cache-config/.gitignore
@@ -27,3 +27,7 @@ t3c-generate/t3c-generate
t3c-preprocess/t3c-preprocess
t3c-request/t3c-request
t3c-update/t3c-update
+
+# generated documentation
+*.1
+*.rst
diff --git a/cache-config/Makefile b/cache-config/Makefile
new file mode 100644
index 0000000..2a9f0b4
--- /dev/null
+++ b/cache-config/Makefile
@@ -0,0 +1,62 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you 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.
+#
+
+SOURCE_DIRS := $(subst /,,$(dir $(wildcard **/README.md)))
+MANPAGES := $(join $(SOURCE_DIRS), $(SOURCE_DIRS:%=/%.1))
+RST := $(join $(SOURCE_DIRS), $(SOURCE_DIRS:%=/%.rst))
+PANDOC_VERSION := $(shell pandoc --version | head -n1 | cut -d ' ' -f2)
+DATE ?= $(shell date '+%Y-%m-%d')
+TC_VERSION ?= $(shell cat ../VERSION)
+
+PANDOC_FLAGS := --strip-comments
+
+.PHONY: man rst clean
+
+man: $(MANPAGES)
+
+%.1: APP=$(subst /,,$(dir $@))
+.SECONDEXPANSION:
+%.1: $$(dir %)/README.md
+ echo '.\" Automatically generated by Pandoc $(PANDOC_VERSION)' > $@
+ echo '.\"' >> $@
+ echo '.TH "$(APP)" "1" "$(DATE)" "$(APP) $(TC_VERSION)" "ATC t3c Manual"' >> $@
+ echo '.hy' >> $@
+ pandoc $(PANDOC_FLAGS) --to man $? >> $@
+
+
+rst: $(RST)
+
+%.rst: APP=$(subst /,,$(dir $@))
+.SECONDEXPANSION:
+%.rst: $$(dir %)/README.md
+ echo ".. highlight:: text" > $@
+ echo "" >> $@
+ echo ".. program:: $(APP)" >> $@
+ echo "" >> $@
+ echo ".. _t3c-$(APP):" >> $@
+ echo "" >> $@
+ echo $(APP) | tr '[:alnum:]-' '*' >> $@
+ echo $(APP) >> $@
+ echo $(APP) | tr '[:alnum:]-' '*' >> $@
+ echo "" >> $@
+ pandoc $(PANDOC_FLAGS) --to rst $? >> $@
+
+
+clean:
+ $(RM) $(MANPAGES) $(RST)
diff --git a/cache-config/README.md b/cache-config/README.md
index e55e3fc..f39ad5e 100644
--- a/cache-config/README.md
+++ b/cache-config/README.md
@@ -1,3 +1,22 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you 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.
+-->
+
# cache-config
Traffic Control cache configuration is done via the `t3c` app and its ecosystem of sub-apps.
@@ -7,3 +26,10 @@ These are provided in the RPM `trafficcontrol-cache-config`.
To apply Traffic Control configuration and changes to caches, users will typically run `t3c` periodically via `cron` or some other system automation mechanism. See [t3c](./t3c/README.md).
The `t3c` app is an ecosystem of apps that work together, similar to `git` and other Linux tools. The `t3c` app itself has commands to proxy the other apps, as well as a mode to generate and apply the entire configuration.
+
+## Documentation
+Each sub-command provides a README.md file. If your system has Pandoc and GNU
+`make` and `date` (UNIX `date` untested, might work - UNIX `make` definitely
+won't), they can also be transformed into Linux/UNIX "manual pages" using
+`make` (or explicitly `make man`) and reStructuredText documentation using
+`make rst`.
diff --git a/docs/Makefile b/docs/Makefile
index 7f4a715..7d43cdb 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -31,6 +31,12 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
.PHONY: all help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+T3C_SOURCE_DIRS := $(patsubst %/,%,$(dir $(wildcard ../cache-config/**/README.md)))
+T3C_RST_SRC := $(join $(T3C_SOURCE_DIRS), $(T3C_SOURCE_DIRS:../cache-config/%=/%.rst))
+T3C_RST_OUT := $(patsubst %,source/admin/t3c/%,$(notdir $(T3C_RST_SRC)))
+
+
+
# WARNING!!!!!!
# 1) do not use underscores, _, in source/conf.py
# 2) do not use incomplete tables in source; tables that contain blank areas between row cell borders cause latex to blow up.
@@ -38,6 +44,15 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# Failure to heed the above will break the latexpdf build target.
all: html
+$(T3C_RST_SRC):
+ @echo $(T3C_SOURCE_DIRS)
+ @echo $(T3C_RST_SRC)
+ @echo $(T3C_RST_OUT)
+ $(MAKE) -C ../cache-config/ rst
+
+$(T3C_RST_OUT): $(T3C_RST_SRC)
+ cp -f $? source/admin/t3c/
+
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@@ -62,43 +77,43 @@ help:
@echo " coverage to run coverage check of the documentation (if enabled)"
clean:
- -rm -rf $(BUILDDIR)
+ -rm -rf $(BUILDDIR) $(T3C_RST_OUT)
$(BUILDDIR):
-mkdir $(BUILDDIR)
-html: $(BUILDDIR)
+html: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-dirhtml: $(BUILDDIR)
+dirhtml: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-singlehtml: $(BUILDDIR)
+singlehtml: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-pickle: $(BUILDDIR)
+pickle: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
-json: $(BUILDDIR)
+json: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
-htmlhelp: $(BUILDDIR)
+htmlhelp: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
-qthelp: $(BUILDDIR)
+qthelp: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -107,7 +122,7 @@ qthelp: $(BUILDDIR)
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/IPCDN_Architecture.qhc"
-devhelp: $(BUILDDIR)
+devhelp: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@@ -116,68 +131,68 @@ devhelp: $(BUILDDIR)
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/IPCDN_Architecture"
@echo "# devhelp"
-epub: $(BUILDDIR)
+epub: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-latex: $(BUILDDIR)
+latex: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
-latexpdf: $(BUILDDIR) latex
+latexpdf: $(BUILDDIR) latex $(T3C_RST_OUT)
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-text: $(BUILDDIR)
+text: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
-man: $(BUILDDIR)
+man: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-texinfo: $(BUILDDIR)
+texinfo: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
-info: $(BUILDDIR)
+info: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-gettext: $(BUILDDIR)
+gettext: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-changes: $(BUILDDIR)
+changes: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
-linkcheck: $(BUILDDIR)
+linkcheck: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
-doctest: $(BUILDDIR)
+doctest: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
-coverage: $(BUILDDIR)
+coverage: $(BUILDDIR) $(T3C_RST_OUT)
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
diff --git a/docs/source/admin/index.rst b/docs/source/admin/index.rst
index 70ad154..a039b1b 100644
--- a/docs/source/admin/index.rst
+++ b/docs/source/admin/index.rst
@@ -49,5 +49,6 @@ Once everything is installed, you will need to configure the servers to talk to
traffic_router.rst
traffic_stats.rst
traffic_server.rst
+ t3c/index.rst
traffic_vault.rst
quick_howto/index.rst
diff --git a/cache-config/.gitignore b/docs/source/admin/t3c/.gitignore
similarity index 75%
copy from cache-config/.gitignore
copy to docs/source/admin/t3c/.gitignore
index 88bf146..fda90ae 100644
--- a/cache-config/.gitignore
+++ b/docs/source/admin/t3c/.gitignore
@@ -16,14 +16,6 @@
# under the License.
#
-# t3c built binaries
-t3c/t3c
-t3c-apply/t3c-apply
-t3c-check/t3c-check
-t3c-check-refs/t3c-check-refs
-t3c-check-reload/t3c-check-reload
-t3c-diff/t3c-diff
-t3c-generate/t3c-generate
-t3c-preprocess/t3c-preprocess
-t3c-request/t3c-request
-t3c-update/t3c-update
+# Generated source files
+*.rst
+!index.rst
diff --git a/docs/source/admin/t3c/index.rst b/docs/source/admin/t3c/index.rst
new file mode 100644
index 0000000..740aef3
--- /dev/null
+++ b/docs/source/admin/t3c/index.rst
@@ -0,0 +1,29 @@
+..
+..
+.. 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.
+..
+
+.. program:: t3c
+
+.. _t3c:
+
+***
+T3C
+***
+:dfn:`t3c` is the tool used to deploy configuration to :term:`cache servers` used by :abbr:`ATC (Apache Traffic Control)`. It stands for "Traffic Control Cache Configuration".
+
+.. toctree::
+ :maxdepth: 3
+ :glob:
+
+ *
diff --git a/docs/source/admin/traffic_server.rst b/docs/source/admin/traffic_server.rst
index 92a77fe..6cbe8a5 100644
--- a/docs/source/admin/traffic_server.rst
+++ b/docs/source/admin/traffic_server.rst
@@ -47,7 +47,7 @@ Installing Traffic Server
#. Install the :term:`t3c` script and run it in 'badass' mode to create the initial configuration
- .. seealso:: :ref:`t3c`
+ .. seealso:: `Configuring Traffic Server`_
#. Start :abbr:`ATS (Apache Traffic Server)`
@@ -74,8 +74,6 @@ Installing Traffic Server
#. Assuming a Traffic Monitor is already installed somewhere, check the "Cache States" table in its Web UI to verify that the :abbr:`ATS (Apache Traffic Server)` server appears.
-.. _t3c:
-
Configuring Traffic Server
==========================
All of the :abbr:`ATS (Apache Traffic Server)` application configuration files are generated by Traffic Ops and installed by :term:`t3c`. The :file:`t3c` file should be installed on all :term:`cache servers` (See `Installing the Cache Config Tool`_), usually in ``/opt/ort``. It is used to do the initial install of the configuration files when the :term:`cache server` is being deployed, and to keep the configuration files up-to-date when the :term:`cache server` is already in service.
diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
index 797b45f..095430d 100644
--- a/docs/source/glossary.rst
+++ b/docs/source/glossary.rst
@@ -425,6 +425,8 @@ Glossary
t3c
The Traffic Control cache config app, used to generate and apply cache configuration files.
+ .. seealso:: For usage and testing documentation, refer to :ref:`t3c`.
+
Tenant
Tenants
Tenancy
diff --git a/infrastructure/docker/build/Dockerfile-docs b/infrastructure/docker/build/Dockerfile-docs
index a82cb5b..2e1d2db 100644
--- a/infrastructure/docker/build/Dockerfile-docs
+++ b/infrastructure/docker/build/Dockerfile-docs
@@ -42,9 +42,16 @@ RUN if [[ ${RHEL_VERSION%%.*} -ge 8 ]]; then \
### docs specific requirements
FROM common-dependencies AS docs
+ARG RHEL_VERSION=8
+
+RUN if [[ ${RHEL_VERSION%%.*} -ge 8 ]]; then \
+ yum -y install dnf-plugins-core && \
+ yum config-manager --set-enabled powertools; \
+ fi
ADD docs/source/requirements.txt /docs.requirements.txt
RUN yum -y install \
+ pandoc \
python3 \
python3-pip \
make && \