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. It can be displayed as a subfolder

of a project or as a dedicated Git repo.

Either way its content can be displayed in 2 ways:

* inline under the `Docs` tab in Pagure:

  * https://pagure.io/docs/<project>/ or</project>

  * https://pagure.io/docs/<namespace>/<project>/</project></namespace>

* standalone:

  * https://docs.pagure.org/<project>/ or</project>

  * https://docs.pagure.org/<namespace>.<project>/</project></namespace>

By default the `Docs` tab in the project's menu is disabled, you

will have to visit the project's settings page and turn it on

in the ``Project options`` section.

The URL to clone the doc repo is:

* https://pagure.io/docs/<namespace>/<project>.git</project></namespace>

To view the doc source files in the browser:

* if the doc repo is kept in the project's sources, use the project's website

* if the doc repo is a dedicated repo, use https://pagure.io/<namespace>/<name></name></namespace>

Different file types can be used for 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.

Updating documentation hosted in a dedicated repo is like

`using other repos <https: docs.pagure.org="" forks.html="" pagure="" usage="">`_.</https:>

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

<https: blob="" doc="" f="" master="" pagure="" pagure.io="">`_. This doc can be built with</https:>

`Sphinx <http: sphinx-doc.org="">`_ to make it HTML and prettier.</http:>

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

<https: docs.pagure.org="" pagure="">`_.</https:>

This is how it is built/updated:

* Clone pagure's sources::

    git clone https://pagure.io/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</project>

containing the doc.

So for pagure it would be something like:

::

    cd pagure/doc

    update_doc.sh pagure