PR#1447: documentation corrections - pagure

pagure

#1447 documentation corrections

Merged 7 years ago by pingou. Opened 7 years ago by billauger.

billauger/pagure docs-patch into master

fix typos, grammar, and add missing keys in doc/configuration.rst

bill auger • 7 years ago

e9ffb5b

fix typos and add dependencies to doc/development.rst

bill auger • 7 years ago

74c1fad

fix typos and formatting in doc/install.rst

bill auger • 7 years ago

2f20e34

doc/configuration.rst

file modified

+89 -74

		`@@ -14,32 +14,32 @@`
		`SECRET_KEY`
		`~~~~~~~~~~`

		`- This key is used by flask to create the session. It should be kept secret`
		`+ This configuration key is used by flask to create the session. It should be kept secret`
		`and set as a long and random string.`


		`SALT_EMAIL`
		`~~~~~~~~~~`

		`- This key is used for when sending notification to ensure that when sending`
		`+ This configuration key is used to ensure that when sending`
		`notifications to different users, each one of them has a different, unique`
		- and un-fakable ``Reply-To`` header that is then used by the milter to find
		+ and un-fakable ``Reply-To`` header. This header is then used by the milter to find
		`out if the response received is a real one or a fake/invalid one.`


		`DB_URL`
		`~~~~~~`

		`- This key indicates to the framework how and where to connect to the database`
		- server. Pagure using `SQLAchemy <http://www.sqlalchemy.org/>`_ it can connect
		`- to a wide range of database server including MySQL, PostgreSQL and SQLite.`
		`+ This configuration key indicates to the framework how and where to connect to the database`
		+ server. Pagure uses `SQLAchemy <http://www.sqlalchemy.org/>`_ to connect
		`+ to a wide range of database server including MySQL, PostgreSQL, and SQLite.`

		`Examples values:`

		`::`

		`- DB_URL=mysql://user:pass@host/db_name`
		`- DB_URL=postgres://user:pass@host/db_name`
		`+ DB_URL = 'mysql://user:pass@host/db_name'`
		`+ DB_URL = 'postgres://user:pass@host/db_name'`
		`DB_URL = 'sqlite:////var/tmp/pagure_dev.sqlite'`

		Defaults to ``sqlite:////var/tmp/pagure_dev.sqlite``
		`@@ -48,7 +48,7 @@`
		`APP_URL`
		`~~~~~~~`

		`- This key indicates the URL at which this pagure instance will be made available.`
		`+ This configuration key indicates the URL at which this pagure instance will be made available.`

		Defaults to: ``https://pagure.org/``

		`@@ -56,11 +56,11 @@`
		`EMAIL_ERROR`
		`~~~~~~~~~~~`

		`- Pagure sends email when it caches an un-expected error (which saves you from`
		`- having to monitor the logs regularly but if you like, the error is still`
		`+ Pagure sends email when it catches an un-expected error (which saves you from`
		`+ having to monitor the logs regularly; but if you like, the error is still`
		`present in the logs).`
		`- This setting allows you to specify to which email address to send these error`
		`- reports.`
		`+ This configuration key allows you to specify to which email address to send`
		`+ these error reports.`


		`GIT_URL_SSH`
		`@@ -85,29 +85,26 @@`
		Defaults to: ``'git://pagure.org/'``


		`- GIT_FOLDER`
		`- ~~~~~~~~~~`
		`-`
		`- This configuration key points to where the folders containing the git repos`
		`- of the projects are located.`
		`+ Repo Directories`
		`+ ----------------`

		`Each project in pagure has 4 git repositories:`

		`- the main repo for the code`
		`- the doc repo showed in the doc server`
		`- - the ticket and request repos storing the metadata of the`
		`- tickets/pull-requests`
		`+ - the ticket repo storing the metadata of the tickets`
		`+ - the request repo storing the metadata of the pull-requests`

		`- There are then another 2 folders specifying the locations of the forks and`
		`- remote git repo used for the remotes pull-requests (ie: pull-request coming`
		`- from a project not hosted on this instance of pagure).`
		`+ There are then another 3 folders: one for specifying the locations of the forks, one`
		`+ for the remote git repo used for the remotes pull-requests (ie: those coming from`
		`+ a project not hosted on this instance of pagure), and one for user-uploaded tarballs.`


		`- FORK_FOLDER`
		`- ~~~~~~~~~~~`
		`+ GIT_FOLDER`
		`+ ~~~~~~~~~~`

		`- This configuration key points to the folder where the git repos of forks of`
		`- the projects are stored.`
		`+ This configuration key points to the folder where the git repos for the`
		`+ source code of the projects are stored.`


		`DOCS_FOLDER`
		`@@ -120,14 +117,14 @@`
		`TICKETS_FOLDER`
		`~~~~~~~~~~~~~~`

		`- This configuration key points to the folder where the git repos storing the`
		`+ This configuration key points to the folder where the git repos for the`
		`metadata of the tickets opened against the project are stored .`


		`REQUESTS_FOLDER`
		`~~~~~~~~~~~~~~~`

		`- This configuration key points to the folder where the git repos storing the`
		`+ This configuration key points to the folder where the git repos for the`
		`metadata of the pull-requests opened against the project are stored.`


		`@@ -139,6 +136,13 @@`
		`project hosted on pagure are stored.`


		`+ UPLOAD_FOLDER_PATH`
		`+ ~~~~~~~~~~~~~~~~~~`
		`+`
		`+ This configuration key points to the folder where user-uploaded tarballs`
		`+ are stored and served from.`
		`+`
		`+`
		`SESSION_COOKIE_SECURE`
		`~~~~~~~~~~~~~~~~~~~~~`

		`@@ -155,7 +159,7 @@`
		`FROM_EMAIL`
		`~~~~~~~~~~`

		`- This setting allows one to specify the email address used by this pagure instance`
		`+ This configuration key specifies the email address used by this pagure instance`
		`when sending emails (notifications).`

		Defaults to: ``pagure@pagure.org``
		`@@ -164,8 +168,8 @@`
		`DOMAIN_EMAIL_NOTIFICATIONS`
		`~~~~~~~~~~~~~~~~~~~~~~~~~~`

		`- This setting allows one to specify the domain used by this pagure instance`
		`- when sending emails (notifications). More precisely, this setting is used`
		`+ This configuration key specifies the domain used by this pagure instance`
		`+ when sending emails (notifications). More precisely, it is used`
		when building the ``msg-id`` header of the emails sent.

		Defaults to: ``pagure.org``
		`@@ -174,7 +178,7 @@`
		`VIRUS_SCAN_ATTACHMENTS`
		`~~~~~~~~~~~~~~~~~~~~~~`

		`- This setting configures whether attachments are scanned for viruses on`
		`+ This configuration key configures whether attachments are scanned for viruses on`
		`upload. For more information, see the install.rst guide.`

		Defaults to: ``False``
		`@@ -192,14 +196,14 @@`
		`GITOLITE_HOME`
		`~~~~~~~~~~~~~`

		`- This configuration key should point to the home of the user under which`
		`- gitolite is run.`
		`+ This configuration key points to the home directory of the user under which`
		`+ gitolite is ran.`


		`GITOLITE_VERSION`
		`~~~~~~~~~~~~~~~~`

		`- This configuration key allows one to specify which version of gitolite you are`
		`+ This configuration key specifies which version of gitolite you are`
		using, it can be either ``2`` or ``3``.

		Defaults to: ``3``.
		`@@ -212,13 +216,20 @@`
		`the public SSH keys of all the user have access to the server.`

		`Since pagure is the user interface, it is pagure that writes down the files`
		`- in this directory effectively setting up the users to be able to use gitolite.`
		`+ in this directory, effectively setting up the users to be able to use gitolite.`
		`+`
		`+`
		`+ GITOLITE_CONFIG`
		`+ ~~~~~~~~~~~~~~~`
		`+`
		`+ This configuration key points to the gitolite.conf file where pagure writes`
		`+ the gitolite repository access configuration.`


		`GL_RC`
		`~~~~~`

		- This configuration key must point to the file ``gitolite.rc`` used by gitolite
		+ This configuration key points to the file ``gitolite.rc`` used by gitolite
		`to record who has access to what (ie: who has access to which repo/branch).`


		`@@ -241,12 +252,12 @@`
		`available. If not defined, pagure will behave as if there are no EventSource`
		`server running.`

		`+`
		`EVENTSOURCE_PORT`
		`~~~~~~~~~~~~~~~~`

		`This configuration key indicates the port at which the EventSource server is`
		`- running. This allows adjusting the port via the configuration file instead`
		`- of hard-coding it in the code.`
		`+ running.`

		.. note:: The EventSource server requires a redis server (see ``Redis options``
		`below)`
		`@@ -281,7 +292,7 @@`
		`REDIS_PORT`
		`~~~~~~~~~~`

		`- This configuration key indicates the port at which the reds server can be`
		`+ This configuration key indicates the port at which the redis server can be`
		`contacted.`

		Defaults to: ``6379``.
		`@@ -289,8 +300,8 @@`
		`REDIS_DB`
		`~~~~~~~~`

		`- This configuration key indicates the name of the redis database to use to`
		`- communicate with the EventSource server.`
		`+ This configuration key indicates the name of the redis database to use for`
		`+ communicating with the EventSource server.`

		Defaults to: ``0``.

		`@@ -301,18 +312,18 @@`
		`ADMIN_GROUP`
		`~~~~~~~~~~~`

		`- List of groups, local or remotes (if the openid server used supports the`
		`- group extension), that are site admin. These admins can regenerate the`
		`- gitolite configuration, the ssh key files, the hook-token for every project`
		`+ List of groups, either local or remote (if the openid server used supports the`
		`+ group extension), that are the site admins. These admins can regenerate the`
		`+ gitolite configuration, the ssh key files, and the hook-token for every project`
		`as well as manage users and groups.`


		`PAGURE_ADMIN_USERS`
		`~~~~~~~~~~~~~~~~~~`

		`- List of usernames that are site admin. These admins have the same rights as`
		`- the user in the admin groups (listed above) as well as admin rights to`
		`- every projects hosted on this pagure instance.`
		`+ List of local users that are the site admins. These admins have the same rights as`
		`+ the users in the admin groups listed above as well as admin rights to`
		`+ all projects hosted on this pagure instance.`


		`Optional options`
		`@@ -338,7 +349,7 @@`
		`ITEM_PER_PAGE`
		`~~~~~~~~~~~~~`
		`This configuration key allows you to configure the length of a page by`
		`- setting the number of items on the page. Items can be commits, users, groups`
		`+ setting the number of items on the page. Items can be commits, users, groups,`
		`or projects for example.`

		Defaults to: ``50``.
		`@@ -347,15 +358,16 @@`
		`SMTP_SERVER`
		`~~~~~~~~~~~`

		`- This configuration key allows one to configure the SMTP server to use when`
		`+ This configuration key specifies the SMTP server to use when`
		`sending emails.`

		Defaults to: ``localhost``.

		`+`
		`SMTP_PORT`
		`~~~~~~~~~`

		`- This configuration key allows one to define the SMTP server port.`
		`+ This configuration key specifies the SMTP server port.`

		`SMTP by default uses TCP port 25. The protocol for mail submission is`
		`the same, but uses port 587.`
		`@@ -364,27 +376,30 @@`

		Defaults to: ``25``

		`+`
		`SMTP_SSL`
		`~~~~~~~~`

		`- This configuration key allows one to specify whether the SMTP connections`
		`- should secured over SSL`
		`+ This configuration key specifies whether the SMTP connections`
		`+ should be secured over SSL.`

		Defaults to: ``False``

		`+`
		`SMTP_USERNAME`
		`~~~~~~~~~~~~~`

		`- This configuration key allows usage of SMTP with auth`
		`+ This configuration key allows usage of SMTP with auth.`

		`Note: Specify SMTP_USERNAME and SMTP_PASSWORD for using SMTP auth`

		Defaults to: ``None``

		`+`
		`SMTP_PASSWORD`
		`~~~~~~~~~~~~~`

		`- This configuration key allows usage of SMTP with auth`
		`+ This configuration key allows usage of SMTP with auth.`

		`Note: Specify SMTP_USERNAME and SMTP_PASSWORD for using SMTP auth`

		`@@ -393,7 +408,7 @@`
		`SHORT_LENGTH`
		`~~~~~~~~~~~~`

		`- This configuration key allows one to configure the length of the commit ids or`
		`+ This configuration key specifies the length of the commit ids or`
		`file hex displayed in the user interface.`

		Defaults to: ``6``.
		`@@ -402,7 +417,7 @@`
		`BLACKLISTED_PROJECTS`
		`~~~~~~~~~~~~~~~~~~~~`

		`- This configuration key allows one to set a list of project name that are forbidden.`
		`+ This configuration key specifies a list of project names that are forbidden.`
		`This list is used for example to avoid conflicts at the URL level between the`
		static files located under ``/static/`` and a project that would be named
		``static`` and thus be located at ``/static``.
		`@@ -421,10 +436,10 @@`
		`CHECK_SESSION_IP`
		`~~~~~~~~~~~~~~~~`

		`- This configuration key allows one to configure whether to check the user's IP`
		`+ This configuration key specifies whether to check the user's IP`
		`address when retrieving its session. This makes things more secure but`
		`- under certain setup it might not work (for example if there are proxies`
		`- in front of the application).`
		`+ under certain setups it might not work (for example if there`
		`+ are proxies in front of the application).`

		Defaults to: ``True``.

		`@@ -432,10 +447,10 @@`
		`PAGURE_AUTH`
		`~~~~~~~~~~~~`

		`- This configuration key allows one to specify which authentication method to use.`
		`- Pagure supports currently two authentication methods, one relying on the`
		`+ This configuration key specifies which authentication method to use.`
		`+ Pagure currently supports two authentication methods: one relying on the`
		Fedora Account System `FAS <https://admin.fedoraproject.org/accounts>`_,
		`- the other relying on local user accounts.`
		`+ and the other using only the local database.`
		It can therefore be either ``fas`` or ``local``.

		Defaults to: ``fas``.
		`@@ -444,11 +459,11 @@`
		`IP_ALLOWED_INTERNAL`
		`~~~~~~~~~~~~~~~~~~~`

		`- This configuration key allows one to specify which IP addresses are allowed`
		`+ This configuration key specifies which IP addresses are allowed`
		`to access the internal API endpoint. These endpoints are accessed by the`
		`- milters for example and allow one to perform action in the name of someone else.`
		`- So they are sensitive, thus the check for the origin of the request using`
		`- these endpoints.`
		`+ milters for example and allow performing actions in the name of someone else`
		`+ which is sensitive, thus the origin of the request using`
		`+ these endpoints is validated.`

		Defaults to: ``['127.0.0.1', 'localhost', '::1']``.

		`@@ -456,7 +471,7 @@`
		`MAX_CONTENT_LENGTH`
		`~~~~~~~~~~~~~~~~~~`

		`- This configuration key allows one to specify the maximum size allowed when`
		`+ This configuration key specifies the maximum file size allowed when`
		`uploading content to pagure (for example, screenshots to a ticket).`

		Defaults to: ``4 * 1024 * 1024`` which corresponds to 4 megabytes.
		`@@ -465,7 +480,7 @@`
		`ENABLE_TICKETS`
		`~~~~~~~~~~~~~~`

		`- This configuration key allows one to activate or de-activate the ticketing system`
		`+ This configuration key activates or de-activates the ticketing system`
		`for all the projects hosted on this pagure instance.`

		Defaults to: ``True``
		`@@ -474,7 +489,7 @@`
		`ENABLE_NEW_PROJECTS`
		`~~~~~~~~~~~~~~~~~~~`

		`- This configuration key allows one to create or forbids creating new projects in`
		`+ This configuration key permits or forbids creation of new projects via`
		`the user interface of this pagure instance.`

		Defaults to: ``True``
		`@@ -483,7 +498,7 @@`
		`ENABLE_DEL_PROJECTS`
		`~~~~~~~~~~~~~~~~~~~`

		`- This configuration key allows one to delete or forbids deleting projects in`
		`+ This configuration key permits or forbids deletiion of projects via`
		`the user interface of this pagure instance.`

		Defaults to: ``True``
		`@@ -492,7 +507,7 @@`
		`EMAIL_SEND`
		`~~~~~~~~~~`

		`- This configuration key allows turning on or off all email notification for`
		`+ This configuration key enables or disables all email notifications for`
		`this pagure instance. This can be useful to turn off when developing on`
		`pagure, or for test or pre-production instances.`

		`@@ -513,7 +528,7 @@`
		`compatibility for URLs using the complete git hash (the 40 characters).`
		`For URLs using a shorter hash, the URLs will remain broken.`

		`- This configuration key allows turning on or off this backward compatibility`
		`+ This configuration key enables or disables this backward compatibility`
		`which is useful for pagure instances running since before 1.3 but is not`
		`for newer instances.`

doc/development.rst

file modified

+20 -5

		`@@ -20,9 +20,24 @@`
		`Dependencies`
		`------------`

		- The dependencies of pagure are listed in the file ``requirements.txt``
		`+ Install the build dependencies of pagure:`
		`+`
		`+ ::`
		`+`
		`+ sudo dnf install git python-virtualenv libgit2-devel \`
		`+ libjpeg-devel gcc libffi-devel redhat-rpm-config`
		`+`
		`+`
		+ The python dependencies of pagure are listed in the file ``requirements.txt``
		`at the top level of the sources.`

		`+ ::`
		`+`
		`+ virtualenv pagure_env`
		`+ source ./pagure_env/bin/activate`
		`+ pip install pygit2==<version of libgit2 found>.* # e.g. 0.23.*`
		`+ pip install -r requirements.txt`
		`+`

		.. note:: working in a `virtualenv <http://www.virtualenv.org/en/latest/>`_
		is tricky due to the dependency on `pygit2 <http://www.pygit2.org/>`_
		`@@ -40,7 +55,7 @@`

		`Create the database scheme::`

		`- ./createdb`
		`+ ./createdb.py`

		`Create the folder that will receive the different git repositories:`

		`@@ -53,14 +68,14 @@`

		`::`

		`- ./runserver`
		`+ ./runserver.py`

		`If you want to change some configuration key you can create a file, place`
		`the configuration change in it and use it with`

		`::`

		`- ./runserver -c <config_file>`
		`+ ./runserver.py -c <config_file>`

		For example, create the file ``config`` with in it:

		`@@ -87,7 +102,7 @@`

		`::`

		`- ./runserver -c config`
		`+ ./runserver.py -c config`

		`To get some profiling information you can also run it as:`

doc/install.rst

file modified

+5 -5

		`@@ -78,7 +78,7 @@`
		`Installing pagure via setup.py`
		`------------------------------`

		- Pagure includes in its sources a ``setup.py`` automatint the installation
		+ Pagure includes in its sources a ``setup.py`` automating the installation
		`of the web applications of pagure (ie: the core + the doc server).`


		`@@ -159,7 +159,7 @@`
		`If installed by RPM, you will find an example apache configuration file`
		at: ``/etc/httpd/conf.d/pagure.conf``.

		`- If not installed by RPM, the example files is present in the sources at:`
		`+ If not installed by RPM, the example file is present in the sources at:`
		``files/pagure.conf``.

		`Adjust it for your needs.`
		`@@ -167,8 +167,8 @@`

		`* Configure the WSGI file`

		`- If you installed by RPM, you will find an example WSGI file at:`
		- ``/usr/share/pagure/pagure.wsgi`` and ``/usr/share/pagure/docs_pagure.wsgi``
		`+ If you installed by RPM, you will find example WSGI files at:`
		+ ``/usr/share/pagure/pagure.wsgi`` for the core server and ``/usr/share/pagure/docs_pagure.wsgi``
		`for the doc server.`

		`If you did not install by RPM, these files are present in the sources at:`
		`@@ -219,7 +219,7 @@`
		`tables, the database scheme.`

		`To create the database tables, you need to run the script`
		- ``/usr/share/pagure/pagure_createdb.py`` and specify it the configuration
		+ ``/usr/share/pagure/pagure_createdb.py`` and specify the configuration
		`file to use via an environment variable.`

		`For example:`

billauger commented 7 years ago

many of the edits to doc/configuration.rst are not strictly corrections but to make the wording more self-consistent

e.g.

"this setting allows ..."
"this configuration key specifies ...:
"this key is used for ...:

pingou commented on line 125 of doc/configuration.rst 7 years ago

This is no longer used since forks are now placed in the same directory as the regular repo (under a forks sub-folder) so it was removed in purpose.

pingou commented on line 204 of doc/configuration.rst 7 years ago

I'm not sure this is use anymore, I seem to remember we changed it so gitolite generates the file itself, I'll have to double-check

pingou commented 7 years ago

Couple of comments but it looks good, thanks :)

billauger commented 7 years ago

removed entry for FORK_DIR

will wait for advice regarding GITOLITE_CONFIG

3 new commits added