diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst deleted file mode 100644 index 3940ee6..0000000 --- a/docs/how-to/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. ATTENTION:: - This documentation is currently in development. We'd be delighted to have your feedback, or even - better, your contributions. If you’d like to help by contributing, fork us on `GitHub - `_! - -############# -How-to guides -############# - -The aim of the documents in this section is not to provide a comprehensive reference, but to take you through the steps of some of the key processes you'll need to work through while using Aldryn. - - -.. toctree:: - :maxdepth: 1 - - create_site - local_development - creating_custom_addon diff --git a/docs/improving.rst b/docs/improving.rst index 7112817..e18972b 100644 --- a/docs/improving.rst +++ b/docs/improving.rst @@ -21,10 +21,10 @@ documentation. In fact if you're not an expert, your opinion is especially impor Documentation structure *********************** -The documentation's structure reflects its three chief functions: +Our documentation is divided into the following main sections: -* :doc:`introduction/index` to introduce concepts and explain basic aspects of the technology -* :doc:`how-to/index` to take the user step-by-step through some key processes +* :doc:`/introduction/index` (``introduction``): step-by-step tutorials to get + you up and running * :doc:`Reference ` to provide in-depth technical reference material As far as possible when writing documentation it should be aimed at a place in one of these @@ -63,24 +63,39 @@ We use Python documentation conventions for section marking: * ``#`` with overline, for parts * ``*`` with overline, for chapters -* ``=``, for sections -* ``-``, for subsections -* ``^``, for subsubsections -* ``"``, for paragraphs +* ``=`` for sections +* ``-`` for subsections +* ``^`` for subsubsections +* ``"`` for paragraphs Inline markup ------------- -* use double backticks - ````settings.py```` - for: - * literals - * filenames - * names of fields and other items in the Admin interface: -* use emphasis - ``*Home*`` for: - * the names of available options in the Admin - * values in or of fields -* use strong emphasis - ``**Control Panel**`` for: - * buttons that perform an action - * the names of key Aldryn components when they are first used in a page or section +* use backticks - `````` - for: + * literals - ````cms.models.pagemodel```` + * filenames - ``edit ``settings.py```` + * names of fields and other specific items in the Admin interface - ``edit ``Redirect```` +* use emphasis - ``*Home*`` - around: + * the names of available options in or parts of the Admin - ``the *Toolbar*`` + * the names of important modes or states - ``switch to *Edit mode*`` + * values in or of fields - ``enter *Home*`` +* use strong emphasis - ``**`` - around: + * buttons that perform an action - ``hit **Save and close**`` + +Rules for using technical words +------------------------------- + +There should be one consistent way of rendering any technical word, depending on its context. +Please follow these rules: + +* when introducing a key term for the the first time, or for the first time in a document, + highlight it to draw attention to it: "**Placeholders** are special model fields" +* in general use, simply use the word as if it were any ordinary word, with no capitalisation or + highlighting: "Your placeholder can now be used." However, use "the Marketplace", "the Network" etc +* at the start of sentences or titles, capitalise in the usual way: "Placeholder management guide" +* when the word refers specifically to an object in the code, highlight it as a literal: + "``Placeholder`` methods can be overwritten as required" - when appropriate, link the term to + further reference documentation as well as simply highlighting it .. _Sphinx: http://sphinx.pocoo.org/ .. _restructuredText: http://docutils.sourceforge.net/docs/ref/rst/introduction.html @@ -88,5 +103,6 @@ Inline markup Internal links -------------- -Please use absolute link paths - `/packaging` - rather than relative paths - `packaging`. It makes -it much easier to update them with a search & replace when files are moved. +Use absolute links to other documentation pages - ``:doc:`/how_to/toolbar``` - +rather than relative links - ``:doc:`/../toolbar```. This makes it easier to +run search-and-replaces when items are moved in the structure. diff --git a/docs/index.rst b/docs/index.rst index 54bf0d8..8fbc9b7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,19 +16,34 @@ Welcome to Aldryn ################# -`Aldryn`_ is an easy-to-use and developer-friendly content management platform. +`Aldryn`_ is a cloud-based platform for Django-based websites. -Aldryn has been designed to meet the needs of: +At the heart of Aldryn is `django CMS`_, a powerful and extensible open-source web content +management system, and a large and growing ecosystem of compatible applications. -* **web content creators**, who require an efficient and reliable way to produce content +Aldryn has been designed to meet the needs of three distinct groups of web professionals. -* **agencies**, who work with multiple clients and content creators, and need to manage them all -* **web developers**, who implement designs and create applications, and need a low-friction - workflow for their deployment +**Content creators**, who require an efficient and reliable way to produce content. + +django CMS and the numerous Addons that can be installed make Aldryn a powerful content creation +platform. A number of Addons already exist in the Aldryn Marketplace, while developers can readily +develop and deploy their own, from new or existing Django packages. + +**Web agencies and designers**, who work with multiple clients and content creators, and need to manage them all. + +Typically they need to provide their clients with a site that the client can subsequently manage on +their own. Aldryn provides flexible and effective ways of setting up sites so that an agency can +then hand the, over to clients, while still being able to retain oversight if necessary. Future - or +indeed continuous - development is possible, because Aldryn has been designed to be a platform as +much for hosting and site management as for development. + +**Web application developers**, who implement designs and create applications, and need a +low-friction workflow for their deployment. + +Aldryn provides a fully-featured Django environment that can easily be recreated locally for +development. -At the heart of Aldryn is `django CMS`_, a powerful and extensible open-source web content -management system, and a large - and growing - ecosystem of compatible applications. The platform also provides: @@ -75,15 +90,8 @@ Table of Contents self introduction/index - how-to/index - reference/sites/index - reference/client/index - reference/addons/index - reference/boilerplates/index - reference/themes/index - reference/workflows_for_agencies/index + reference/index improving - glossary .. _Aldryn: http://www.aldryn.com/ .. _django CMS: http://django-cms.org/ diff --git a/docs/how-to/create_site.rst b/docs/introduction/create_site.rst similarity index 100% rename from docs/how-to/create_site.rst rename to docs/introduction/create_site.rst diff --git a/docs/how-to/creating_custom_addon.rst b/docs/introduction/creating_custom_addon.rst similarity index 95% rename from docs/how-to/creating_custom_addon.rst rename to docs/introduction/creating_custom_addon.rst index d8f4fb1..27f26f9 100644 --- a/docs/how-to/creating_custom_addon.rst +++ b/docs/introduction/creating_custom_addon.rst @@ -1,6 +1,6 @@ -===================== +##################### Create a custom Addon -===================== +##################### In the :doc:`/introduction/index` we got an Aldryn site running in a local environment. If you haven't got to that stage yet, you should follow that tutorial first before returning here to continue. @@ -9,8 +9,9 @@ An Addon must conform to certain standards, but apart from some minor additional long as your Addon is well-packaged you should not encounter any difficulty. The good news is that Aldryn even helps package it. +********************************* Create a simple django CMS plugin -================================= +********************************* For the purposes of this walkthrough, we'll create a basic plugin that greets the logged-in user by name. @@ -68,8 +69,9 @@ Try it out: start the runserver, and add your plugin to a page .. _package_your_addon: +****************** Package your Addon -================== +****************** Creating packages, especially if you've not done it before, can be tricky and frustrating to get right. The Aldryn Control Panel takes much of the hard work out of the process for you, automatically generating several of the files @@ -91,7 +93,7 @@ your Addon. Let's download and look at these files one-by-one. ``addon.json`` --------------- +============== The special requirements for Addon packaging are dealt with in an ``addon.json`` file containing information about the Addon. They are are in discussed in further detail in :ref:`addon-packaging`, but in brief it contains a dictionary @@ -106,32 +108,32 @@ know how to use Python's packaging to ensure that they're actually installed alo In fact all these files can be edited to meet more complex needs. ``setup.py`` ------------- +============ An Addon needs to be packaged in the usual Python way, starting with the ``setup.py`` file. Again, Aldryn provides a minimal but adequate file ready for you to use. ``MANIFEST.in`` ---------------- +=============== The ``MANIFEST.in`` file lists the locations of resources such as templates that need to be included in an installation. ``LICENSE.txt`` ---------------- +=============== A licence file is required. This may not matter very much if you're just using your application on your own sites, but if you plan to put it on the Aldryn Marketplace you should think carefully about appropriate licence terms. ``README.rst`` --------------- +============== Your ``README.rst`` will be empty until you provide a ``Description`` and **Save** the Addon - but of course you can edit the README file manually too. ``__init.py__`` ---------------- +=============== Finally, you have an ``__init.py__`` that provides a ``__version__`` (that starts at "0.0.1" by default). @@ -151,8 +153,9 @@ like:: views.py templates +******** Test it! -======== +******** The Aldryn client includes a validation tool, that will report on problems it finds in your Addon. @@ -168,8 +171,9 @@ Now check, in your local development environment, that your newly-packaged Addon that some of your Addon's components are available to Django not because you've packaged them correctly, but simply in virtue of where you have put them while working on them! +*********************** Add further information -======================= +*********************** If your Addon's only for private use, you don't need to add more. If you'd like other people to make use of it, add some more information about it. ``Additional information`` is particularly aimed at other developers who may be @@ -179,8 +183,9 @@ browsing the Aldryn Marketplace. ``Publish on django-cms.org`` will mean that it's also listed amongst the `django CMS Addons `_. +******* Upload -====== +******* When you're satisfied that all is correct, you're ready to upload your Addon to Aldryn:: @@ -191,8 +196,9 @@ Your Addon is now in the Aldryn Marketplace and ready to be installed. Once it has been uploaded, you have the option to make your Addon publicly available in its configuration settings, from the Control Panel. Note that once made public, an Addon can't be made private again. +****************** Install and deploy -================== +****************** In an Aldryn project Control Panel, install the Addon now as you'd install any other, and deploy your changes. A few minutes later, you should be up and running and able to use your application in Aldryn. diff --git a/docs/introduction/index.rst b/docs/introduction/index.rst index d6faf1b..8ed0777 100644 --- a/docs/introduction/index.rst +++ b/docs/introduction/index.rst @@ -1,42 +1,18 @@ -############ -Introduction -############ +.. ATTENTION:: + This documentation is currently in development. We'd be delighted to have your feedback, or even + better, your contributions. If you’d like to help by contributing, fork us on `GitHub + `_! -Aldryn is a cloud-based platform for Django-based websites. +######### +Tutorials +######### -.. toctree:: - :maxdepth: 1 - - Key concepts - Key tools - -================ -Aldryn's purpose -================ - -Aldryn is designed to meet the needs of three distinct groups of web professionals: +The aim of the documents in this section is not to provide a comprehensive reference, but to take you through the steps of some of the key processes you'll need to work through while using Aldryn. -* content creators -* agencies and designers -* web application developers -In order to meet the multifarious and sometimes competing needs of these three groups, Aldryn -provides a suite of integrated tools and workflows. - -**Content creators** are served by django CMS and the Aldryn Addons that can be installed. A number -of Addons already exist in the Aldryn Marketplace, but developers can readily develop and deploy -their own, from new or existing Django packages. - -**Web agencies and designers** typically need to provide their clients with a site that the client -can subsequently manage on their own, working with tools and developers they are experienced with, -and able to work with rapidly. Aldryn provides flexible and effective ways of setting up sites so -that an agency can then hand over to clients, while still being able to retain oversight if -necessary. Future - or indeed continuous - development is possible, because Aldryn has been -designed to be a platform as much for hosting and site management as for development. +.. toctree:: + :maxdepth: 1 -For **web application developers**, Aldryn provides a fully-featured Django environment. At the -same time it is a strongly-opinionated environment, which is of course necessary to permit it to -function as a cloud-based offering, that can be managed without difficulty by a non-technical user -using the Control Panel. Aldryn solves the problem of meeting these competing needs by making -possible **Local Development** in an environment (supported by tools that build it automaticallu) -that replicates the cloud environment. + create_site + local_development + creating_custom_addon diff --git a/docs/how-to/local_development.rst b/docs/introduction/local_development.rst similarity index 95% rename from docs/how-to/local_development.rst rename to docs/introduction/local_development.rst index a8c5946..4fae4f8 100644 --- a/docs/how-to/local_development.rst +++ b/docs/introduction/local_development.rst @@ -1,6 +1,6 @@ -====================================== +###################################### Aldryn's local development environment -====================================== +###################################### If your code works with django CMS, you can expect it to work with Aldryn. @@ -17,22 +17,22 @@ replicates as far as possible the one your code will encounter when deployed. or even better, your contributions `. This documentation is on `GitHub `_ - +********************************** Replicate your Aldryn site locally -================================== +********************************** You'll need the :ref:`Aldryn command-line client ` installed, and a site - even the most basic one will do - that's active on Aldryn. The Aldryn client ------------------ +================= The client's available from PyPI:: pip install aldryn-client Replicate your Aldryn site locally ----------------------------------- +================================== Login to your Aldryn account:: @@ -56,7 +56,7 @@ created. Within it you'll find: * ``dev`` - a directory that Aldryn puts on the Python path for your convenience Set up the local database -------------------------- +========================= You'll need to get a local copy of your Aldryn database running. @@ -72,7 +72,7 @@ Using your local PostgreSQL database client, import the ``database.dump`` file, the new database's name and any permissions match those in the local site's settings. Use local settings ------------------- +================== You're going to need to adjust the settings for your local version of the project, so that it can use your local database. @@ -112,7 +112,7 @@ installed in the project on Aldryn):: ] Let's go --------- +======== You need to activate this new virtualenv, install the requirements and fire up the Django runserver:: diff --git a/docs/reference/addons/addon-configuration.rst b/docs/reference/addons/addon-configuration.rst index 7f058c0..32fc6c7 100644 --- a/docs/reference/addons/addon-configuration.rst +++ b/docs/reference/addons/addon-configuration.rst @@ -1,46 +1,46 @@ +################### Addon Configuration -=================== +################### -If you want to provide configuration (and a nice form) for your app, you may add a file -``aldryn_config.py`` to the root of your app (next to setup.py). This configuration form will -then be displayed on the detail page of the installed addon on the controlpanel. +Your Addon may have some Django settings, that would nortmally be provided in ``settings.py``. It's not possible to +have direct access to ``settings.py`` on Aldryn, but Aldryn provides an interface to it. -.. image:: ../../_static/addons/screenshot_addon_configuration.png +You can make these settings available to your Addon's user through a web form where appropriate. For example, if +your application needs to provide an API key to another service, your Addon can ask the user to supply this information +when it's installed. + +*************** +Create the form +*************** + +Add a file ``aldryn_config.py`` to the root of your application (i.e. in the same directory as its ``setup.py``); this +will contain the information for the form. This file **must** contain a class named ``Form`` which **must** subclass ``aldryn_client.forms.BaseForm``. -The ``Form`` class may contain any number of form fields. +The ``Form`` class then contains the fields you want to add to your web form on Aldryn. Available fields are: -* ``aldryn_client.forms.CharField`` +* ``aldryn_client.forms.CharField`` (takes optional ``max_length`` and ``min_length`` arguments) * ``aldryn_client.forms.CheckboxField`` -* ``aldryn_client.forms.SelectField`` -* ``aldryn_client.forms.NumberField`` -* ``aldryn_client.forms.StaticFileField`` +* ``aldryn_client.forms.SelectField`` (takes a list of tuples as a required second argument) +* ``aldryn_client.forms.NumberField`` (takes optional ``min_value`` and ``max_value`` arguments) +* ``aldryn_client.forms.StaticFileField`` (takes an optional ``extensions`` argument which is a list of valid file extensions) -All fields must provide a label as first argument and take a keyword argument named ``required`` to indicate +All fields **must** provide a label as first argument, and provide a keyword argument named ``required`` to indicate whether this field is required or not. -Additionally, all fields support ``help_text`` and ``initial`` keyword arguments. - -``CharFields`` take optional ``max_length`` and ``min_length`` arguments. - -``SelectField`` takes a list of tuples (Django style) as required second argument). - -``NumberField`` has optional ``min_value`` and ``max_value`` arguments. -``StaticFileField`` takes an optional ``extensions`` argument which is a list of valid file extensions. +All fields also support ``help_text`` and ``initial`` keyword arguments. +.. image:: ../../_static/addons/screenshot_addon_configuration.png -Generating settings -------------------- - -To generate settings, define a ``to_settings`` method which takes two arguments: - -* A cleaned data of your form -* A dictionary of existing settings (which contains ``MIDDLEWARE_CLASSES`` and ``DEBUG``). +Custom field validation +======================= -Add the settings you want on to the settings dictionary and return it. +If you need custom field validation, subclass a field and overwrite its ``clean`` method. This takes a single argument +(the value to clean) and should return a cleaned value or raise ``aldryn_client.forms.ValidationError`` with a helpful +message about why the validation failed. Example: @@ -50,23 +50,25 @@ Example: from aldryn_client import forms - class Form(forms.BaseForm): + class EvenNumberField(forms.NumberField): + def clean(self, value): + value = super(EvenNumberField, self).clean(value) + if value % 2 != 0: + raise forms.ValidationError('Please provide an even number') + else: + return value - ... - def to_settings(self, cleaned_data, settings_dict): - if settings_dict.get('DEBUG'): - settings_dict['EMAIL_BACKEND'] = 'django.core.mail.backends.console.EmailBackend' - return settings_dict +******************* +Generating settings +******************* +To generate settings, define a ``to_settings`` method which takes two arguments: +* the ``cleaned_data`` of your form +* a dictionary of some existing settings:``MIDDLEWARE_CLASSES``, ``DEBUG`` and ``TEMPLATE_CONTEXT_PROCESSORS``. -Custom field validation ------------------------ - -If you want to have custom field validation, subclass a field and overwrite it's ``clean`` method, -which takes a single argument (the value to clean) and should return a cleaned value or raise -``aldryn_client.forms.ValidationError`` with a nice message as to why the validation failed. +You can manipulate these existing settings, and add any new ones your Addon requires. Example: @@ -76,19 +78,11 @@ Example: from aldryn_client import forms - class EvenNumberField(forms.NumberField): - def clean(self, value): - value = super(EvenNumberField, self).clean(value) - if value % 2 != 0: - raise forms.ValidationError('Please provide an even number') - else: - return value - + class Form(forms.BaseForm): -Extending the Toolbar ---------------------- + ... -To create a better user experience, django CMS 3 provides a way of extending the toolbar so you could add entrues such -as **Block > Add new entry** to make it easier for the user to use your addon. A detailed guide can be found within -the django CMS documentation: -http://django-cms.readthedocs.org/en/develop/extending_cms/toolbar.html + def to_settings(self, cleaned_data, settings_dict): + if settings_dict.get('DEBUG'): + settings_dict['EMAIL_BACKEND'] = 'django.core.mail.backends.console.EmailBackend' + return settings_dict diff --git a/docs/reference/addons/first-steps.rst b/docs/reference/addons/first-steps.rst deleted file mode 100644 index 8c28db4..0000000 --- a/docs/reference/addons/first-steps.rst +++ /dev/null @@ -1,6 +0,0 @@ -First steps -=========== - -First make sure :ref:`aldryn-client is installed and configured `. - - diff --git a/docs/reference/addons/index.rst b/docs/reference/addons/index.rst index c686cc4..769fe56 100644 --- a/docs/reference/addons/index.rst +++ b/docs/reference/addons/index.rst @@ -2,36 +2,12 @@ Addons ====== -Addons are the building blocks for your website. An Addon is a re-usable django app with some -extra metadata that makes it work on aldryn. - -Todo: - -* dependency definitions (in setup.py, version ranges) -* migration rules (never delete) -* baseproject compatibility (to Django & django CMS version? or to base-project version?) -* sitemap.xml integration (an api/app?) -* multilingual rules -* draft/publish rules -* template naming and structure rules -* Boilerplate support rules -* cms integration rules - * plugin naming - * toolbar integration guidelines - * apphook guidelines - * exception handling in apphooks/plugins (should not break with no apphook defined yet) - * adding default apphook on installation - -when available: - -* search integration rules -* celery rules - +An Addon is a re-usable Django appplication with some extra metadata that allows it to be deployed +in an Aldryn project. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - first-steps packaging addon-configuration code-conventions diff --git a/docs/reference/addons/packaging.rst b/docs/reference/addons/packaging.rst index 496b1a2..3cd33e5 100644 --- a/docs/reference/addons/packaging.rst +++ b/docs/reference/addons/packaging.rst @@ -1,120 +1,101 @@ +####################### +Packaging Aldryn Addons +####################### + +An Addon is a re-usable Django appplication with some extra metadata that allows it to be deployed +in an Aldryn project. + .. _addon-packaging: -Packaging and Sourcecode -======================== +********* +Packaging +********* + +See :ref:`package_your_addon` for step-by-step instructions on packaging a Django application as +an Addon. + +In general though, an Addon needs to be a standard Python application with a ``setup.py`` and so on. -If you want to write an addon, write a standard Django app (including working setup.py!). +addon.json +========== -An addon requires a configuration file named ``addon.json`` which follows the general json guidelines. -Place this file next to your setup.py and you should be ready to run ``aldryn addon validate``. +In addition, it requires a configuration file named ``addon.json`` which follows the general json +guidelines. -All addons **must** have a valid license file. Preferably called ``LICENSE.txt`` in the root -of the Project. -The following is an example of a configuration file using all options: +``addon.json`` has two required keys, ``package-name`` and ``installed-apps``: .. code-block:: json { - "name": "My Addon", - "description": "This is my custom application.", - "url": "https://github.com/aldryn", "package-name": "my-addon", "installed-apps": [ "my_addon" ], - "author": { - "name": "Divio", - "url": "https://www.aldryn.com" - }, - "license": { - "name": "BSD" - } } -.. NOTE:: Please follow a strict :ref:`Versioning Scheme `! - - Options ------- -.. option:: name - - The name of your Boilerplate - -.. option:: description - - A description of your Boilerplate - -.. option:: version - - The version of this Boilerplate (must be compatible with LooseVersion) - -.. option:: url - - The url to your repository or website - .. option:: package—name - The **package** name of your app (the thing you have in the setup.py under ``name``) + The **package** name of your app. Generally it makes sense to use the name of your package given + its the setup.py under ``name``, but it doesn't have to be the same - this is Aldryn's internal + name for the package. .. option:: installed—apps - A list of apps that needs to be added to the ``INSTALLED_APPS`` to make your app work. - -.. option:: author - - .. option:: name: - - Your name! - - .. option:: url: - - URL to your website (optional) + A list of apps that needs to be added to the ``INSTALLED_APPS`` of the project's ``settings.py`` + to make your app work. -.. option:: license +``setup.py`` +============ - .. option:: name: +A standard ``setup.py``. - Type of the license, e.g. BSD, MIT +You are **strongly advised** to download the one Aldryn provides automatically and use that, making +any amendments (for example to ``install_requires``) as necessary. +``setup()`` **must** provide a version number. Aldryn relies on this to provide information about +updates, so it must be incremented properly. The Aldryn-provided version of ``setup.py`` follows +the convention of getting the version number from ``__init__.py``. -Source Repository Guidelines ----------------------------- +``LICENSE.txt`` +=============== -Use our cookie-cutter template for addons: https://github.com/divio/cookiecutter-aldryn-addon +All Addons that are to be shared **must** have a valid license file, called ``LICENSE.txt``, in the +root of the Project. You can upload an Addon without a license file, but you won't be able to share +it. -The Source should contain: +When :ref:`creating your Addon in the Aldryn interface ` creating your Addon +in the Aldryn interface, you can choose a suitable licence from the list available and download a +suitable one, or you can create your own. ``README.rst`` -~~~~~~~~~~~~~~ - -A short introduction what the package is about. Installation instructions (non-aldryn, like with any other package) - -.. TODO:: more guidelines. link to someplace where this is well described. +============== -Include a link back to aldryn +Note that this file **must** be called ``README.rst``. -* rst: ``This package is compatible with `Aldryn `_.`` -* markdown: ``This package is compatible with [Aldryn](http://www.aldryn.com).`` +Please include: -``LICENSE.txt`` -~~~~~~~~~~~~~~~ +* a short introduction what the package is about +* installation instructions for non-Aldryn users +* information about Aldryn compatibility +* links to Aldryn, documentation, the official source repository -.. TODO:: links/description of common licenses +``MANIFEST.in`` +=============== -http://en.wikipedia.org/wiki/List_of_software_licenses +A standard manifest file. +Aldryn provides one for download that will work for most packages. -``MANIFEST.in`` -~~~~~~~~~~~~~~~ +``__init__.py`` +=============== -:: +You are recommended to use the ``__init__.py`` provided by Aldryn for download (see the note about +version numbering above). - include LICENSE.txt - include README.rst - recursive-include mypackage/templates * - recursive-include mypackage/static * - recursive-include mypackage/locale * - recursive-exclude * *.pyc +We recommend a version number in the format:: + __version__ = "0.0.1" diff --git a/docs/reference/addons/template-structure.rst b/docs/reference/addons/template-structure.rst index 2142b83..ef12c2b 100644 --- a/docs/reference/addons/template-structure.rst +++ b/docs/reference/addons/template-structure.rst @@ -1,72 +1,59 @@ +################## Template Structure -================== +################## -To keep addons in sync, we recomment some guidelines in how to structure the templates folder. +.. note:: + In this document we assume you are working with a standard Aldryn Boilerplate that uses the `Aldryn Boilerplates + `_ helper package. These follow certain patterns, and you are + encouraged to follow them too. -Base Template -------------- + You **don't have to follow these conventions**, though we recommend that you do. Following them will mean your Addon + will be more likely to play nicely with other Addons, behave in ways that other users and developers expect and + generally be a useful and valued contribution to the Aldryn ecosystem. -If your addon provides **apphook** functionalities, your single point of entry should be a ``base.html`` which extends -the roots base. For example: + So, treat all directions in this document, unless explicitly indicated otherwise, as recommendations that you can + choose not to follow. -.. code-block:: text - templates/ - ├─ aldryn_blog/ - │ └─ base.html - └─ base.html +This documentation extends the official django CMS `Developing addon applications: best practices +`_. It's important to note that within the Aldryn ecosystem +these recommendations are much stronger, and in some cases define *requirements*, not just good practices, so treat the +recommendations there with due respect. -This way we can ensure your addon is extending your general layout and adds additional functionalities. But this is -not all. The roots *base.html* should contain a block content: ``{% block content %}{% endblock content %}``. With -this convention in mind, you can easily create a layout which also works for all addons. Your apps base.html would -look something like: +==================================================== +Maintaining compatibility with multiple Boilerplates +==================================================== -.. code-block:: html +Your Addon may have templates that are simple enough to be **compatible** with multiple Boilerplates. Typically though, +you can **enhance** your Addon's templates' by adapting them to a particular Boilerplate - for example, applying +CSS classes to the elements in the HTML to take advantage of the Boilerplate's CSS and JavaScript provisions. - {% extends "base.html" %} - {% block content %} -
- {% block blog_content %}{% endblock %} -
- {% endblock content %} +In this case, for each Boilerplate you'd like to support, also add a set of templates at:: -The **block blog_content** ensures that your addon has its own block extension to work with so all sub templates -have a common ground. + boilerplates/boilerplate_name/templates/ +For example:: -Addons ------- + aldryn_addon + templates/ + aldryn_addon/ + base.html + boilerplates/ + aldryn_boilerplate_bootstrap3/ + templates/ + aldryn_addon/ + base.html + boilerplate_name/ + templates/ + aldryn_addon/ + base.html -To structure addons (plugins), we recommend using a separate folder **addons** within your app. The name of the -added html file should represent the functionality of the addon. Here an example of our previous structure: +and do this for as many Boilerplates as you wish to support. -.. code-block:: text +This does of course mean more work for you as a project maintainer. The payoff is enhanced compatibility with multiple +Boilerplates. When uploading your Addon to the Marketplace, ensure that you indicate which Boilerplates get special +support in this way. - templates/ - ├─ aldryn_blog/ - │ ├─ plugins - │ │ └─ latest_posts.html - │ └─ base.html - └─ base.html - -This way we get a good idea of where to find addons which can be injected using django CMS plugin system and apphook -functionalities. In some cases addons provide different themes or variants like the gallery. A recommended structure -there would be something like: - -.. code-block:: text - - templates/ - ├─ aldryn_gallery/ - │ └─ plugins - │ ├─ base.html - │ ├─ feature/ - │ │ └─ gallery.html - │ └─ standard/ - │ └─ gallery.html - └─ base.html - -In this case the gallery provides two kind of templates, a standard version and a feature version. Both gallery.html -files extend ``aldryn_gallery/plugins/base.html`` in order to keep some common elements in one file. Yet that base.html -is nowhere called from within the addon. The backend just picks standard/gallery.html or feature/gallery.html according -to the settings within the plugin. +For more general information about good practices in creating Addons, see `Developing addon applications: best practices +`_ in the official django CMS documentation. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 6823fde..fa96a04 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -1,8 +1,10 @@ +######### +Reference +######### + +Technical reference material. + .. toctree:: + :maxdepth: 2 - sites/index - client/index - addons/index - boilerplates/index - themes/index - workflows_for_agencies/index + addons/index \ No newline at end of file diff --git a/docs/introduction/concepts.rst b/docs/topics/concepts.rst similarity index 100% rename from docs/introduction/concepts.rst rename to docs/topics/concepts.rst diff --git a/docs/topics/index.rst b/docs/topics/index.rst new file mode 100644 index 0000000..e69de29 diff --git a/docs/introduction/tools.rst b/docs/topics/tools.rst similarity index 100% rename from docs/introduction/tools.rst rename to docs/topics/tools.rst