From 884ead7dad03835f6c5aa12b482b3a0029e12877 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Feb 20 2016 10:22:41 +0000 Subject: [PATCH 1/9] Make theming easily doable with pagure Using flask-multistatic and jinja2's options one can simply override one of the static files or templates provided to customize it per its needs. --- diff --git a/pagure/__init__.py b/pagure/__init__.py index eaac804..526a37c 100644 --- a/pagure/__init__.py +++ b/pagure/__init__.py @@ -33,8 +33,10 @@ from pygments import highlight from pygments.lexers.text import DiffLexer from pygments.formatters import HtmlFormatter +from flask_multistatic import MultiStaticFlask + # Create the application. -APP = flask.Flask(__name__) +APP = MultiStaticFlask(__name__) APP.jinja_env.trim_blocks = True APP.jinja_env.lstrip_blocks = True @@ -45,6 +47,35 @@ if 'PAGURE_CONFIG' in os.environ: APP.config.from_envvar('PAGURE_CONFIG') +if APP.config.get('THEME_TEMPLATE_FOLDER', False): + # Jinja can be told to look for templates in different folders + # That's what we do here + template_folder = APP.config['THEME_TEMPLATE_FOLDER'] + if template_folder[0] != '/': + template_folder= os.path.join( + APP.root_path, APP.template_folder, template_folder) + import jinja2 + # Jinja looks for the template in the order of the folders specified + templ_loaders = [ + jinja2.FileSystemLoader(template_folder), + APP.jinja_loader, + ] + APP.jinja_loader = jinja2.ChoiceLoader(templ_loaders) + + +if APP.config.get('THEME_STATIC_FOLDER', False): + static_folder = APP.config['THEME_STATIC_FOLDER'] + if static_folder[0] != '/': + static_folder= os.path.join( + APP.root_path, 'static', static_folder) + # Unlike templates, to serve static files from multiples folders we + # need flask-multistatic + APP.static_folder = [ + static_folder, + os.path.join(APP.root_path, 'static'), + ] + + import pagure.doc_utils import pagure.forms import pagure.lib From 24ef744960aa571514a4229826a08ed1c15054ce Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Feb 20 2016 10:22:41 +0000 Subject: [PATCH 2/9] Add the new dependency on flask-multistatic where needed --- diff --git a/files/pagure.spec b/files/pagure.spec index b726a7a..afbf3ed 100644 --- a/files/pagure.spec +++ b/files/pagure.spec @@ -26,6 +26,7 @@ BuildRequires: python-cryptography BuildRequires: python-docutils BuildRequires: python-flask BuildRequires: python-flask-wtf +BuildRequires: python-flask-multistatic BuildRequires: python-markdown BuildRequires: python-psutil BuildRequires: python-pygit2 >= 0.20.1 @@ -60,6 +61,7 @@ Requires: python-docutils Requires: python-enum34 Requires: python-flask Requires: python-flask-wtf +Requires: python-flask-multistatic Requires: python-markdown Requires: python-psutil Requires: python-pygit2 >= 0.20.1 diff --git a/requirements-fedora.txt b/requirements-fedora.txt index 511229f..d062896 100644 --- a/requirements-fedora.txt +++ b/requirements-fedora.txt @@ -9,6 +9,7 @@ python-enum34 python-fedora-flask python-flask python-flask-wtf +python-flask-multistatic python-jinja2 python-markdown python-munch diff --git a/requirements.txt b/requirements.txt index 89ade4e..9b40360 100644 --- a/requirements.txt +++ b/requirements.txt @@ -9,6 +9,7 @@ docutils enum34 flask flask-wtf +flask-multistatic html5lib # required by bleach kitchen markdown From 70457742d1daac1e58b018d480e0d7597bc2decd Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Feb 20 2016 10:26:10 +0000 Subject: [PATCH 3/9] Start documenting a little how theming pagure works --- diff --git a/doc/theming.rst b/doc/theming.rst new file mode 100644 index 0000000..988f93f --- /dev/null +++ b/doc/theming.rst @@ -0,0 +1,15 @@ +Theme your pagure +================= + +Pagure via `flask-multistatic `_ +offers the possibility to override the default theme allowing to customize +the style of your instance. + +By default pagure looks for its templates and static files in the folders +``pagure/templates`` and ``pagure/static``, but you can ask pagure to look +for templates and static files in another folder. + +By specifying the configuration keys ``THEME_TEMPLATE_FOLDER`` and +``THEME_STATIC_FOLDER`` in pagure's configuration file, you tell pagure to +look for templates and static files first in these folders, then in its +usual folders. From 1342a68eb8114c7b3556855ed70127dd55808d82 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Feb 20 2016 10:35:55 +0000 Subject: [PATCH 4/9] Give a little example on how you can customize/theme pagure --- diff --git a/doc/theming.rst b/doc/theming.rst index 988f93f..a51efec 100644 --- a/doc/theming.rst +++ b/doc/theming.rst @@ -13,3 +13,43 @@ By specifying the configuration keys ``THEME_TEMPLATE_FOLDER`` and ``THEME_STATIC_FOLDER`` in pagure's configuration file, you tell pagure to look for templates and static files first in these folders, then in its usual folders. + + +Let's take an example, you wish to replace the pagure logo at the top right +of all the pages. + +This logo is part of the ``master.html`` template which all pages inherit +from. So what you want to do is replace this ``master.html`` by your own. + +* First, create the folder where your templates and static files will be stored: + +:: + + mkdir /var/www/mypaguretheme/templates + mkdir /var/www/mypaguretheme/static + +* Place your own logo in the static folder + +:: + + cp /path/to/your/logo /var/www/mypaguretheme/static + +* Place in there the original ``master.html`` + +:: + + cp /path/to/original/pagure/templates/master.html /var/www/mypaguretheme/templates + +* Edit it and replace the url pointing to the pagure logo (around line 27) + +:: + + - Date: Feb 21 2016 06:38:40 +0000 Subject: [PATCH 5/9] Include the file name in the command --- diff --git a/doc/theming.rst b/doc/theming.rst index a51efec..9035834 100644 --- a/doc/theming.rst +++ b/doc/theming.rst @@ -32,7 +32,7 @@ from. So what you want to do is replace this ``master.html`` by your own. :: - cp /path/to/your/logo /var/www/mypaguretheme/static + cp /path/to/your/my-logo.png /var/www/mypaguretheme/static * Place in there the original ``master.html`` From 9dd1c0a79079f8f85cf16392424007571b1dfa1d Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Feb 21 2016 06:39:17 +0000 Subject: [PATCH 6/9] Add a note about the fact that file names must be identical --- diff --git a/doc/theming.rst b/doc/theming.rst index 9035834..a7b14c0 100644 --- a/doc/theming.rst +++ b/doc/theming.rst @@ -15,6 +15,11 @@ look for templates and static files first in these folders, then in its usual folders. +.. note: The principal is that pagure will look in the folder specified in + the configuration file first and then in its usual folder, so the + **file names must be identical**. + + Let's take an example, you wish to replace the pagure logo at the top right of all the pages. From 129555db63b1f403f477f1710a4f86e072695148 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Feb 21 2016 06:39:46 +0000 Subject: [PATCH 7/9] Add a title to the section with the example --- diff --git a/doc/theming.rst b/doc/theming.rst index a7b14c0..cedaf65 100644 --- a/doc/theming.rst +++ b/doc/theming.rst @@ -19,6 +19,8 @@ usual folders. the configuration file first and then in its usual folder, so the **file names must be identical**. +Example +------- Let's take an example, you wish to replace the pagure logo at the top right of all the pages. From d66fc1ebf617e1e6aad8429ea2527675c3ed2d59 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Feb 21 2016 06:40:08 +0000 Subject: [PATCH 8/9] Final notes on theming pagure --- diff --git a/doc/theming.rst b/doc/theming.rst index cedaf65..961b4ab 100644 --- a/doc/theming.rst +++ b/doc/theming.rst @@ -60,3 +60,22 @@ from. So what you want to do is replace this ``master.html`` by your own. + THEME_STATIC_FOLDER='/var/www/mypaguretheme/static' * Restart pagure + + +.. note: you could just have replaced the `pagure-logo.png` file with your + own logo which would have avoided overriding the template. + + +In production +------------- + +Serving static files via flask is fine for development but in production +you will probably want to have apache server them. This will allow caching +either on the server side or on the client side. + +You can ask apache to behave in a similar way as does flask-multistatic with +flask here, ie: search in one folder and if you don't find the file look +in another one. + +`An example apache configuration `_ +is provided as part of the sources of `flask-multistatic `_. From 04619ce8022f33ed024128cb84954609e2a280d5 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Feb 21 2016 06:45:23 +0000 Subject: [PATCH 9/9] Start an Usage section in the doc and include theming there --- diff --git a/doc/index.rst b/doc/index.rst index b838116..268c3e3 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -36,6 +36,7 @@ Contents: install_webhooks configuration development + usage contributing contributors diff --git a/doc/usage.rst b/doc/usage.rst new file mode 100644 index 0000000..6253d99 --- /dev/null +++ b/doc/usage.rst @@ -0,0 +1,13 @@ +Usage +===== + +Using pagure should come fairly easily, especially to people already used +to forges such as GitHub or GitLab. There are however some tips and tricks +which can be useful to know and that this section of the doc covers. + +Contents: + +.. toctree:: + :maxdepth: 2 + + theming