Skip to content

Home

Jump to bottom
mradamcox edited this page Jul 3, 2019 · 15 revisions

This repo holds the content that is published at https://arches.readthedocs.io, the official location for Arches documentation.

branch/release versioning

A separate branch is maintained for each minor release of Arches, from 2.1 to the current release. For more recent releases you will see branches for each micro release as well, but out-of-date minor release branches may not be maintain or published.

In Read the Docs, the branch with the highest version number will be used for the "stable" build (arches.readthedocs.io/en/stable), while the master branch will be used for the "latest" build (arches.readthedocs.io/en/latest).

Any documentation for unreleased features should be committed to master. Any documentation updates for existing releases should be committed to the appropriate branch, and where applicable we use git cherry-pick to apply the commits to master as well.

Merging between version branches should not happen.

contributing

We welcome documentation contributions. Please begin by forking this repo. If you aren't in the GitHub loop, feel free to add an Issue to this repo describing the changes that you'd like to see.

To document new/unreleased features, make a branch off of master, commit your changes, and make a PR against master.

To update documentation for the current stable release, make a new branch from the highest numbered branch. Name it something like <version>_<description of change>, commit your changes, and then make a PR against the original branch. We can then cherry-pick those commits into master (or you can do so by branching from master, running git cherry-pick <hash>, and making a PR against master).

make a local build

  • to install

    git clone https://github.com/<your name>/arches-docs
cd arches-docs
pip install -r requirements.txt

  • to build

    cd docs
make html

  • to view, open _build/html/index.html in a browser

  • to build a non-master version, checkout the appropriate branch

    git fetch --all
git checkout 4.1.1 origin/4.1.1
make html

    you may want to delete the _build directory between builds of different versions, or if big changes have been made

links within the docs

Use the :ref: directive to link to any header anywhere in the docs, doesn't matter what page it is on. Two examples:

See :ref:`Arches Collector Workflow` for more information.

See Arches Collector Workflow for more information.

See the :ref:`collector docs <Arches Collector Workflow>` for more information.

See collector docs for more information.

In these examples there is a header (of any level) somewhere that is something like

Arches Collector Workflow
-------------------------

resources

Clone this wiki locally