This repository houses the end-user documentation for F5's Container Ingress Services (CIS). The documentation is published at https://clouddocs.f5.com/containers/latest.
We write documentation in reStructuredText (rST); build with Sphinx ; test with Travis-CI ; and publish to a static website hosted in Amazon s3.
If you want to contribute to this documentation set, please consult the F5 Open Source Style Guide and training first. Once you've completed the training and are ready to start writing, fork this repo.
- Create an issue corresponding to the changes/additions you plan to make. When your work is complete, open a pull request.
- Be sure to fetch and rebase often so your fork stays up-to-date!
This project uses CI/CD to build, test, and deploy documentation.
Tools:
- sphinx: builds HTML, checks syntax, and tests links.
- f5-sphinx-theme: F5 theme for sphinx projects.
- write-good: tests grammar.
- Travis-CI: builds, tests, and deploys documentation.
- AWS S3/CloudFront: website hosting.
- Docker image: f5devcentral/containthedocs
Scripts:
The scripts directory contains documentation testing resources. We recommend running the test script before opening a pull request; if the build associated with your PR doesn't pass, the request won't be accepted.
The test script can be run locally or in a Docker container, which uses the F5 containthedocs image. The Ubuntu-based Docker image has all of the dependencies required to build the project documentation pre-installed. If you want to run the test script locally, you'll need to install the requirements first.
- docker-docs: Runs a Docker container mounted to your working directory.
- test-docs: Runs the HTML build, grammar check, and linkcheck.
You can use the commands below to build and test your work. Commands beginning with docker run in a Docker container using the same image used in Travis-CI (f5devcentral/containthedocs).
You can view the documentation in a web browser on your local machine.
| Command | Description | How to view docs |
|---|---|---|
| make html | basic HTML build | open docs/_build/html/index.html |
| make preview | builds docs as you write; view changes live in browser | open http://0.0.0.0:8000 |
| make test | run the docs quality tests | open docs/_build/html/index.html |
| make docker-html | Runs the docker-docs script with make HTML;
uses the same container image as production builds |
open docs/_build/html/index.html |
| make docker-preview | Runs the docker-docs script with make preview;
uses the same container image as production builds |
open http://0.0.0.0:8000 |
| make docker-test | Runs the docker-docs script with make test;
uses the same container image as production builds |
open docs/_build/html/index.html |
Note
If you don't use the Docker container, you need to install the project dependencies locally. You can find instructions for installing/using virtualenv and pip here.
virtualenv <my-venv> pip install -r requirements.txt npm install write-good
See the F5 Open Source Documentation style guide for rST and sphinx cheat sheets, as well as general guidelines for writers.
Individuals or business entities who contribute to this project must have completed and submitted the F5 Contributor License Agreement prior to their code submission being included in this project.
To report an issue or request additional guides, please open an Issue. Use the issue template provided and, please, be specific!
See Support.
Copyright 2015-2018 F5 Networks Inc.
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.