Skip to content

Commit

Permalink
A wholesale restructuring of the documentation.
Browse files Browse the repository at this point in the history 
The existing content (some of which will have to be reworked to fit better) is
now in the following main sections:

* Getting started (introduction): step-by-step tutorials and guides to
  get you up and running
* How-to guides (how_to): guides covering more advanced development
* Key topics (topics): explanations of key parts of the system
* Reference (reference): technical reference for APIs, key models and
  so on
* Development & community (contributing)
* Using django CMS (user): guides for using rather than setting up or
  developing for the CMS
* Release notes & upgrade information (upgrade)
  • Loading branch information
@evildmp
evildmp committed Nov 9, 2014
1 parent 91cd323 commit e0e5bf2
Show file tree
Hide file tree
Showing 41 changed files with 362 additions and 353 deletions.
221 changes: 11 additions & 210 deletions CONTRIBUTING.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,23 +3,25 @@ Contributing to django CMS
##########################

Like every open-source project, django CMS is always looking for motivated
individuals to contribute to its source code. However, to ensure the highest
code quality and keep the repository nice and tidy, everybody has to follow a
few rules (nothing major, I promise :) )
individuals to contribute to its source code.

There's more guidance on `how to contribute in our documentation <http://docs.django-cms.org/en/latest/introduction
>`_.

Key points:

.. ATTENTION::

If you think you have discovered a security issue in our code, please report
it **privately**, by emailing us at `security@django-cms.org`_.

Please don't raise it on:

* IRC
* GitHub
* either of our email lists

or in any other public forum until we have had a chance to deal with it.
or in any other public forum until we have had a chance to deal with it.


*********
Expand All @@ -30,215 +32,14 @@ People interested in developing for the django CMS should join the
`django-cms-developers`_ mailing list as well as heading over to #django-cms on
the `freenode`_ IRC network for help and to discuss the development.

You may also be interested in following `@djangocmsstatus`_ on twitter to get the
GitHub commits as well as the hudson build reports. There is also a `@djangocms`_
account for less technical announcements.


*************
In a nutshell
*************

Here's what the contribution process looks like, in a bullet-points fashion, and
only for the stuff we host on GitHub:

#. django CMS is hosted on `GitHub`_, at https://github.com/divio/django-cms
#. The best method to contribute back is to create an account there, then fork
the project. You can use this fork as if it was your own project, and should
push your changes to it.
#. When you feel your code is good enough for inclusion, "send us a `pull
request`_", by using the nice GitHub web interface.



*****************
Contributing Code
*****************


Getting the source code
=======================

If you're interested in developing a new feature for the CMS, it is recommended
that you first discuss it on the `django-cms-developers`_ mailing list so as
not to do any work that will not get merged in anyway.

- Code will be reviewed and tested by at least one core developer, preferably
by several. Other community members are welcome to give feedback.
- Code *must* be tested. Your pull request should include unit-tests (that cover
the piece of code you're submitting, obviously)
- Documentation should reflect your changes if relevant. There is nothing worse
than invalid documentation.
- Usually, if unit tests are written, pass, and your change is relevant, then
it'll be merged.

Since we're hosted on GitHub, django CMS uses `git`_ as a version control system.

The `GitHub help`_ is very well written and will get you started on using git
and GitHub in a jiffy. It is an invaluable resource for newbies and old timers
alike.


Syntax and conventions
======================

We try to conform to `PEP8`_ as much as possible. A few highlights:

- Indentation should be exactly 4 spaces. Not 2, not 6, not 8. **4**. Also, tabs
are evil.
- We try (loosely) to keep the line length at 79 characters. Generally the rule
is "it should look good in a terminal-base editor" (eg vim), but we try not be
[Godwin's law] about it.

It is worth to mention that we use **tabs** within HTML, SASS/SCSS and JavaScript.
Please refrain from using spaces anywhere except if it helps code readability.


Process
=======

This is how you fix a bug or add a feature:

#. `fork`_ us on GitHub.
#. Checkout your fork.
#. *Hack hack hack*, *test test test*, *commit commit commit*, test again.
#. Push to your fork.
#. Open a pull request.

And at any point in that process, you can add: *discuss discuss discuss*,
because it's always useful for everyone to pass ideas around and look at thngs
together.

:ref:`testing` is really important: a pull request that lowers our testing
coverage will only be accepted with a very good reason; bug-fixing patches
**must** demonstrate the bug with a test to avoid regressions and to check
that the fix works.

We have an IRC channel, our `django-cms-developers`_ email list,
and of course the code reviews mechanism on GitHub - do use them.


**************************
Contributing Documentation
**************************

Perhaps considered "boring" by hard-core coders, documentation is sometimes even
more important than code! This is what brings fresh blood to a project, and
serves as a reference for old timers. On top of this, documentation is the one
area where less technical people can help most - you just need to write
semi-decent English. People need to understand you. We don't care about style or
correctness.

Documentation should be:

- Written using valid `Sphinx`_/`restructuredText`_ syntax (see below for specifics)
and the file extension should be ``.rst``.
- Written in British English. We could discuss how it would bring more people to the
project by having a Klingon or some other translation, but that's a problem we
will confront once we already have good documentation in English.
- Accessible. You should assume the reader to be moderately familiar with
Python and Django, but not anything else. Link to documentation of libraries
you use, for example, even if they are "obvious" to you (South is the first
example that comes to mind - it's obvious to any Django programmer, but not to
any newbie at all).
A brief description of what it does is also welcome.

Pulling of documentation is pretty fast and painless. Usually somebody goes over
your text and merges it, since there are no "breaks" and that GitHub parses rst
files automagically it's really convenient to work with.

Also, contributing to the documentation will earn you great respect from the
core developers. You get good karma just like a test contributor, but you get
double cookie points. Seriously. You rock.

Simple changes, such as fixing typographical errors, can be made directly via Github.
If you are making significant changes such as adding new files, we recommend
that you make these changes on your local machine and test them before submitting.
Follow the same steps above to fork and clone the project locally.
Next, create a virtualenv so you can install the documentation tools::

virtualenv djcms-docs-env
source djcms-docs-env/bin/activate
pip install sphinx sphinx_rtd_theme

Now you can ``cd`` into the ``django-cms/docs`` directory and build the documentation::

make html
open build/html/index.html

This allows you to review your changes in your local browser.
After each change, be sure to rebuild the docs using ``make html``.
If everything looks good, then it's time to push your changes to Github and open a
pull request.

Documentation markup
====================


Sections
--------

We use Python documentation conventions for section marking:

* ``#`` with overline, for parts
* ``*`` with overline, for chapters
* ``=``, for sections
* ``-``, for subsections
* ``^``, for subsubsections
* ``"``, for paragraphs

Inline markup
-------------

* use backticks - ````settings.py```` - for:
* literals
* filenames
* names of fields and other items in the Admin interface:
* use emphasis - ``*Home*`` around:
* the names of available options in the Admin
* values in or of fields

************
Translations
************

For translators we have a `Transifex account
<https://www.transifex.com/projects/p/django-cms/>`_ where you can translate
the .po files and don't need to install git or mercurial to be able to
contribute. All changes there will be automatically sent to the project.


.. raw:: html

Top translations django-cms core:<br/>

<img border="0" src="https://www.transifex.com/projects/p/django-cms/resource/core/chart/image_png"/>


********
Frontend
********


We are using `SASS/Compass <compass-style.org>`_ for our styles. The files
are located within ``cms/static/cms/sass`` and can be compiled using the compass
command ``compass watch cms/static/cms/`` from within the django-cms root.

This will invoke the **config.rb** within ``cms/static/cms/`` using the predefined
settings.
You may also be interested in following `@djangocmsstatus`_ on twitter to get
the GitHub commits as well as the hudson build reports. There is also a
`@djangocms`_ account for less technical announcements.


.. _security@django-cms.org: mailto:security@django-cms.org
.. _fork: http://github.com/divio/django-cms
.. _Sphinx: http://sphinx.pocoo.org/
.. _PEP8: http://www.python.org/dev/peps/pep-0008/
.. _django-cms-developers: http://groups.google.com/group/django-cms-developers
.. _GitHub : http://www.github.com
.. _GitHub help : http://help.github.com
.. _freenode : http://freenode.net/
.. _@djangocmsstatus : https://twitter.com/djangocmsstatus
.. _@djangocms : https://twitter.com/djangocms
.. _pull request : http://help.github.com/send-pull-requests/
.. _git : http://git-scm.com/
.. _restructuredText: http://docutils.sourceforge.net/docs/ref/rst/introduction.html

16 changes: 0 additions & 16 deletions docs/advanced/index.rst
View file

This file was deleted.

Loading

0 comments on commit e0e5bf2

Please sign in to comment.