Skip to content

F5Networks/f5-ci-docs

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

f5-ci-docs

https://travis-ci.com/F5Networks/f5-ci-docs.svg?branch=master

Overview

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.

Contributing

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!

How to Build, Test, and Deploy Documentation

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.

Building and Testing

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

Tips and Tricks

See the F5 Open Source Documentation style guide for rST and sphinx cheat sheets, as well as general guidelines for writers.

Contributor License Agreement

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.

Issues

To report an issue or request additional guides, please open an Issue. Use the issue template provided and, please, be specific!

Support

See Support.

Copyright and License

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.