From 9b713349392cc46e8b9837b76d295a1c691f4212 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 22 2016 21:50:06 +0000 Subject: Expand the documentation with some information on how to use the doc repo --- diff --git a/doc/usage.rst b/doc/usage.rst index 0f7e850..310384a 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -11,6 +11,7 @@ Contents: :maxdepth: 2 first_steps + using_doc ticket_templates pr_custom_page theming diff --git a/doc/using_doc.rst b/doc/using_doc.rst new file mode 100644 index 0000000..850595e --- /dev/null +++ b/doc/using_doc.rst @@ -0,0 +1,113 @@ +Using the doc repository of your project +======================================== + +On the overview page of your project, on the menu on the right side, are +presented the `Source GIT URLs`. Next to this title is a little `more` button. +If you click on this, you can see three more sections appearing: `Docs +GIT URLs`, `Issues GIT URLs` and `Pull Requests GIT URLs`. + +Each section correspond to one of the four git repositories created for each +project: + +* 1 git repository containing the source code, displayed in the main section + of the pagure project. +* 1 git repository for the documentation +* 1 git repository for the issues and their metadata +* 1 git repository for the metadata for pull-requests + +In this section of the documentation, we are intersting in the doc repository. + +The doc repository is a simple git repo, whose content will appear under the +`Docs` tab in pagure and in https://docs.pagure.org//. + +There are 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. + +* 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 output of this building is 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/ + pushd $1 + git commit -av + git push + popd + + rm -rfI _build + rm -rfI $1 + +It can be used by running `update_doc.sh ` from within the folder +containing the doc. + +So for pagure it would be something like: + +:: + + cd pagure/doc + update_doc.sh pagure