Using the doc repository of your project

In this section of the documentation, we are interested in the doc repository.

The doc repository is a simple git repo, whose content will appear under the Docs tab in pagure and on https://docs.pagure.org/<project>/.

There are a few ways you can put your documentation in this repo:

• Simple text files

Pagure will display them as plain text. If one of these is named index it will be presented as the front page.

• rst or markdown files

Pagure will convert them to html on the fly and display them as such. The rst files must end with .rst and the markdown ones must end with .mk, .md or simply .markdown.

• html files

Pagure will simply show them as such.

Example

Pagure’s documentation is kept in pagure’s sources, in the doc folder there. You can see it at: https://pagure.io/pagure/blob/master/f/doc. This doc can be built with sphinx to make it html and prettier.

The built documentation is available at: https://docs.pagure.org/pagure/.

This is how it is built/updated:

• Clone pagure’s sources:

  git clone https://pagure.io/docs/pagure.git
  

• Move into its doc folder:

  cd pagure/doc
  

• Build the doc:

  make html
  

• Clone pagure’s doc repository:

  git clone ssh://git@pagure.io/docs/pagure.git
  

• Copy the result of sphinx’s build to the doc repo:

  cp -r _build/html/* pagure/
  

• Go into the doc repo and update it:

  cd pagure
  git add .
  git commit -am "Update documentation"
  git push
  

• Clean the sources:

  cd ..
  rm -rf pagure  # remove the doc repo
  rm -rf _build  # remove the output from the sphinx's build
  

To make things simpler, the following script (name update_doc.sh) can be used:

#!/bin/bash

make html

git clone "ssh://git@pagure.io/docs/$1.git"
cp -r _build/html/* $1/
(
    cd $1
    git add .
    git commit -av
    git push
)

rm -rfI _build
rm -rfI $1

It can be used by running update_doc.sh <project> from within the folder containing the doc.

So for pagure it would be something like:

cd pagure/doc
update_doc.sh pagure