Blame doc/using_doc.rst

Pierre-Yves Chibon 9b7133
Using the doc repository of your project
Pierre-Yves Chibon 9b7133
========================================
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
On the overview page of your project, on the menu on the right side, are
Pierre-Yves Chibon 9b7133
presented the `Source GIT URLs`. Next to this title is a little `more` button.
Pierre-Yves Chibon 9b7133
If you click on this, you can see three more sections appearing: `Docs
Pierre-Yves Chibon 9b7133
GIT URLs`, `Issues GIT URLs` and `Pull Requests GIT URLs`.
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
Each section correspond to one of the four git repositories created for each
Pierre-Yves Chibon 9b7133
project:
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 5bdf0e
* A git repository containing the source code, displayed in the main section
Pierre-Yves Chibon 9b7133
  of the pagure project.
Pierre-Yves Chibon 5bdf0e
* A git repository for the documentation
Pierre-Yves Chibon 5bdf0e
* A git repository for the issues and their metadata
Pierre-Yves Chibon 5bdf0e
* A git repository for the metadata for pull-requests
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 5bdf0e
In this section of the documentation, we are interested in the doc repository.
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
The doc repository is a simple git repo, whose content will appear under the
Pierre-Yves Chibon 5bdf0e
`Docs` tab in pagure and on https://docs.pagure.org/<project>/.</project>
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 5bdf0e
There are a few ways you can put your documentation in this repo:
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
* Simple text files
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
Pagure will display them as plain text. If one of these is named ``index``
Pierre-Yves Chibon 9b7133
it will be presented as the front page.
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
* rst or markdown files
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
Pagure will convert them to html on the fly and display them as such.
Pierre-Yves Chibon 5bdf0e
The rst files must end with `.rst` and the markdown ones must end with
Pierre-Yves Chibon 5bdf0e
``.mk``, ``.md`` or simply ``.markdown``.
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
* html files
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
Pagure will simply show them as such.
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 5bdf0e
.. note: By default the `Docs` tab in the project's menu is disabled, you
Pierre-Yves Chibon 5bdf0e
         will have to visit the project's settings page and turn it on
Pierre-Yves Chibon 5bdf0e
         in the ``Project options`` section.
Pierre-Yves Chibon e9515f
Pierre-Yves Chibon e9515f
Pierre-Yves Chibon 9b7133
Example
Pierre-Yves Chibon 9b7133
-------
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
Pagure's documentation is kept in pagure's sources, in the `doc` folder there.
Pierre-Yves Chibon 9b7133
You can see it at: `https://pagure.io/pagure/blob/master/f/doc
Pierre-Yves Chibon 9b7133
<https: blob="" doc="" f="" master="" pagure="" pagure.io="">`_. This doc can be built with</https:>
Pierre-Yves Chibon 9b7133
`sphinx <http: sphinx-doc.org="">`_ to make it html and prettier.</http:>
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 5bdf0e
The built documentation is available at: `https://docs.pagure.org/pagure/
Pierre-Yves Chibon 9b7133
<https: docs.pagure.org="" pagure="">`_.</https:>
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 5bdf0e
This is how it is built/updated:
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
* Clone pagure's sources::
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
    git clone https://pagure.io/docs/pagure.git
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
* Move into its doc folder::
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
    cd pagure/doc
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
* Build the doc::
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
    make html
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
* Clone pagure's doc repository::
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
    git clone ssh://git@pagure.io/docs/pagure.git
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
* Copy the result of sphinx's build to the doc repo::
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
    cp -r _build/html/* pagure/
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
* Go into the doc repo and update it::
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
    cd pagure
Pierre-Yves Chibon 9b7133
    git add .
Pierre-Yves Chibon 9b7133
    git commit -am "Update documentation"
Pierre-Yves Chibon 9b7133
    git push
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
* Clean the sources::
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
    cd ..
Pierre-Yves Chibon 9b7133
    rm -rf pagure  # remove the doc repo
Pierre-Yves Chibon 9b7133
    rm -rf _build  # remove the output from the sphinx's build
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
To make things simpler, the following script (name `update_doc.sh`) can be
Pierre-Yves Chibon 9b7133
used:
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
::
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
    #!/bin/bash
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
    make html
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
    git clone "ssh://git@pagure.io/docs/$1.git"
Pierre-Yves Chibon 9b7133
    cp -r _build/html/* $1/
Pierre-Yves Chibon 111849
    (
Pierre-Yves Chibon 111849
        cd $1
Pierre-Yves Chibon 9a4323
        git add .
Pierre-Yves Chibon 111849
        git commit -av
Pierre-Yves Chibon 111849
        git push
Pierre-Yves Chibon 111849
    )
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
    rm -rfI _build
Pierre-Yves Chibon 9b7133
    rm -rfI $1
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
It can be used by running `update_doc.sh <project>` from within the folder</project>
Pierre-Yves Chibon 9b7133
containing the doc.
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
So for pagure it would be something like:
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
::
Pierre-Yves Chibon 9b7133
Pierre-Yves Chibon 9b7133
    cd pagure/doc
Pierre-Yves Chibon 9b7133
    update_doc.sh pagure