From 9b713349392cc46e8b9837b76d295a1c691f4212 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 22 2016 21:50:06 +0000 Subject: [PATCH 1/4] 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 From e9515fe817f90e53e6ec6534e62c01a964290a22 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 22 2016 21:53:05 +0000 Subject: [PATCH 2/4] Add a note about enabling the Docs tab --- diff --git a/doc/using_doc.rst b/doc/using_doc.rst index 850595e..05b45b1 100644 --- a/doc/using_doc.rst +++ b/doc/using_doc.rst @@ -36,6 +36,10 @@ Pagure will convert them to html on the fly and display them as such. Pagure will simply show them as such. +.. note: By default the `Docs` tab in the project's menu is off, you will + have to visit the project's settings page to turn it on. + + Example ------- From 5bdf0e463902aa7ee839de0c58213ef5d2eaa35f Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 22 2016 23:40:10 +0000 Subject: [PATCH 3/4] Adjust the using_doc documentation based on @puiterwijk's feedback --- diff --git a/doc/using_doc.rst b/doc/using_doc.rst index 05b45b1..b9fc325 100644 --- a/doc/using_doc.rst +++ b/doc/using_doc.rst @@ -9,18 +9,18 @@ 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 +* A 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 +* A git repository for the documentation +* A git repository for the issues and their metadata +* A git repository for the metadata for pull-requests -In this section of the documentation, we are intersting in the doc repository. +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 in https://docs.pagure.org//. +`Docs` tab in pagure and on https://docs.pagure.org//. -There are few ways you can put your documentation in this repo: +There are a few ways you can put your documentation in this repo: * Simple text files @@ -30,14 +30,17 @@ 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. -.. note: By default the `Docs` tab in the project's menu is off, you will - have to visit the project's settings page to turn it on. +.. note: 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. Example @@ -48,10 +51,10 @@ 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/ +The built documentation is available at: `https://docs.pagure.org/pagure/ `_. -This is how it is built/updated. +This is how it is built/updated: * Clone pagure's sources:: From 111849d646432a4a7c67636e4f1ec1b2de44c9bd Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 22 2016 23:44:37 +0000 Subject: [PATCH 4/4] Improve the update_docs shell script with the help of @puiterwijk --- diff --git a/doc/using_doc.rst b/doc/using_doc.rst index b9fc325..54660c2 100644 --- a/doc/using_doc.rst +++ b/doc/using_doc.rst @@ -101,10 +101,11 @@ used: git clone "ssh://git@pagure.io/docs/$1.git" cp -r _build/html/* $1/ - pushd $1 - git commit -av - git push - popd + ( + cd $1 + git commit -av + git push + ) rm -rfI _build rm -rfI $1