Home

This repo holds the official Arches documentation, published at https://arches.readthedocs.io. It uses reStructuredText, built with Sphinx.

logging an issue

Feel free to add an Issue to this repo describing any problems you see in our documentation, or changes that you think would be beneficial. Add labels if appropriate.

branch/release versioning

A separate branch is maintained for each minor release of Arches, from 2.1 to the current release.

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 specific commits to master as well.

Merging between version branches should never happen.

contributing

We welcome content contributions. Please begin by forking this repo.

• To document new/unreleased features (latest)

  • Make a new branch from master
  • Commit your changes -- push to your repo
  • Make a PR against master.

• To update documentation for the current release (stable)

  • Make a new branch from the highest numbered branch.
  • Name it something like <version>_<description of change>, e.g. 5.0_update_installation_steps
  • Commit your changes -- push to your repo
  • Make a PR against the original (highest numbered) 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).

Thank you!

making a local build

• to install

  first create and activate a python virtual environment. then:

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

• to build

  cd docs
  make html
  

• to view, open docs/_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

patterns to follow when writing

internal links to other documentation sections

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

Given that there is a header (of any level) somewhere in the documentation that looks like

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

Example 1

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

Result: See Arches Collector Workflow for more information.

Example 2

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

Result: See the collector docs for more information.

images with links to themselves

If you want an image that is a hyperlink to the file itself, use a figure instead of an image. The figure is automatically turned into a link, but only if a height or width attribute is set.

.. figure:: images/datamodel-arches-4.4.1-032119.svg
    :width: 100%
    :align: center

    Data model showing only Arches models. (including a caption is optional but encouraged)

Previously we had used

.. image:: images/datamodel-full-4.4.1-032119.svg
    target: /_images/datamodel-full-4.4.1-032119.svg

and while this works on a local build, it does not work when published in RTD (https://github.com/archesproject/arches-docs/issues/120).

resources

• Arches code-base: https://github.com/archesproject/arches
• Arches user forum: https://groups.google.com/forum/#!forum/archesproject
• reStructuredText primer: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

release ticket label greens

#00ef39 #00da34 #00c52e #00a527 #00781c #006b19 #005a15 #00480e #003f0a