This repository contains the files and code used to generate the documentation pages for the ACES project.
The docs at https://docs.acescentral.com are built from the head of the main branch and should be considered the most up-to-date.
We welcome contributions of any kind to our documentation. This includes pull requests that are ready to be merged in immediately, unformatted content, or even just an idea for a page that you'd like to have added to the documentation.
If you have a specific idea or a request for a particular topic that you would like to see explained, please create an issue so that we can track and prioritize new additions to the documentation.
The ACES Documentation website is built using MkDocs using the Material for MkDocs theme to generate HTML from the Markdown text files. The site configuration, including navigation, is managed through the mkdocs.yml file.
Changes are automatically deployed through a GitHub Action when commits are made to the main branch. Updates on main appear on https://docs.acescentral.com.
To update existing content, simply modify the relevant .md file.
To add new pages, create a .md file and add a reference to it in the nav: section of mkdocs.yml.
Using Docker with the included Dockerfile, you can build a local version of the docs to preview your changes locally to make sure they appear exactly as you want before submitting your pull request.
- Ensure Docker is installed and running.
- In your terminal, navigate to the local clone of the
aces-docsrepository. - Type the command:
docker compose upThis will spin up a Docker container for aces-docs. - If the build completes and the Docker container is running, a local version of the doc site will then be viewable at http://0.0.0.0:8000.
- The doc site should then reload the html whenever changes are made to the files and then saved. Adjust your files, save, and preview the changes immediately until you are satisfied.
Once satisfied with your updates, proceed to submit a pull request.
Even if you are "not a programmer" or just lack comfortability with contributing through the Git workflow, you can still contribute!
All documentation content is generated from simple Markdown text files. This means it is easy to contribute even if you are intimidated by the overhead of forking, building a local copy, and then submitting back a pull request. Just send the content-including any text and any accompanying images or graphics-and we can help you get it formatted into Markdown that will build properly for the documentation.
Before any contributions can be accepted, contributors must sign a Contributor License Agreement (CLA) to ensure that the project can freely use your contributions. You can find more details and instructions on how to sign the CLA in the CONTRIBUTING.md file.
ACES Documentation is licensed under the Creative Commons Attribution 4.0 International License.
For support on ACES, please visit ACESCentral.com or on the #ACES channel on the ASWF Slack