Rewrote manual installation how-to documentation #5826

Merged
merged 6 commits into from Jan 4, 2017

Projects

None yet

3 participants

@evildmp
Contributor
evildmp commented Dec 28, 2016

Completely rewrites http://docs.django-cms.org/en/stable/how_to/install.html, removing out-of-date and hard-to-keep-updated sections.

Brings everything else up-to-date, and better in line with http://docs.django-cms.org/en/stable/introduction/index.html.

@coveralls

Coverage Status

Coverage remained the same at 82.598% when pulling 2d9134a on evildmp:docs-improve-manual-installation into 291028b on divio:release/3.4.x.

@evildmp evildmp requested a review from czpython Dec 28, 2016
@coveralls

Coverage Status

Coverage remained the same at 82.598% when pulling 5d04f7a on evildmp:docs-improve-manual-installation into 291028b on divio:release/3.4.x.

@coveralls

Coverage Status

Coverage remained the same at 82.598% when pulling fd497b4 on evildmp:docs-improve-manual-installation into 291028b on divio:release/3.4.x.

README.rst
@@ -56,14 +56,27 @@ More information on `our website <http://www.django-cms.org>`_.
Requirements
************
-django CMS requires Django 1.8, and Python 2.7, 3.3 or 3.4.
+See the `Python/Django requirements for the current release version
+<http://http://docs.django-cms.org/en/stable/#software-version-requirements-and-release-notes>`_ in our documentation.
@czpython
czpython Dec 31, 2016 Member

invalid link?

@evildmp
evildmp Jan 3, 2017 Contributor

It's invalid right now, but this very pull request will make it valid.

@czpython
czpython Jan 3, 2017 Member

I meant that http is there twice

@evildmp
evildmp Jan 3, 2017 Contributor

When you put it like that...

README.rst
-the details on how to install, extend and use the django CMS.
+We maintain documentation for several versions of the project. Key versions are:
+
+* `stable <http://http://docs.django-cms.org>`_ (default), for the **current release** version
@czpython
czpython Dec 31, 2016 Member

shouldn't these links and others be https?

@evildmp
evildmp Jan 3, 2017 edited Contributor

No - not at present, anyway. If you use https:
screenshot 2017-01-03 12 49 17

docs/how_to/install.rst
-Recommended
-===========
+Check the :ref:`Python/Django requirements <requirements>` for this version of django CMS.
@czpython
czpython Dec 31, 2016 Member

I would say "Check the .. section for this version of django CMS."

docs/how_to/install.rst
-These packages are not *required*, but they provide useful functionality with
-minimal additional configuration and are well-proven.
+django CMS also has other requirements, which it lists as dependencies in its ``setup.py``.
@czpython
czpython Dec 31, 2016 Member

we shouldn't link to setup.py, the requirements section above should contain all dependencies including the ones in setup.py

@evildmp
evildmp Jan 3, 2017 Contributor

That's exactly what I want to get away from.

The requirements listed in setup.py will always be the actual requirements, whereas the ones listed here will inevitably become out-of-date or incorrect (as they were before). Unless we can guarantee that a list here will be updated whenever someone touches setup.py, I don't want to include it.

@czpython
czpython Jan 3, 2017 Member

Then shouldn't we just link to the setup.py and not have a Python/Django requirements <requirements> section

@evildmp
evildmp Jan 3, 2017 Contributor

I think that having the Python and Django (and only the Python and Django) version requirements in the home page of the documents is fine, with the README and any other documentation (like the install documentation) pointing at that single authoritative place.

We should not have requirements lists buried away in the documentation - once, on the home page, is OK though, and it would be a bit weird not to have any mention of them there.

docs/how_to/install.rst
-.. _PostgreSQL: http://www.postgresql.org/
-.. _MySQL: http://www.mysql.com
+You can also add ``'cms.middleware.utils.ApphookReloadMiddleware'``. It's not absolutely necessary, but it's
+:ref:`useful <reloading_apphooks>`. It needs to be as close to the start of the list as possible.
@czpython
czpython Dec 31, 2016 Member

technically it should be the first one

docs/how_to/install.rst
+ Django applications. django CMS defines blocks for CSS and JavaScript, and requires these two Sekizai tags. We
+ recommended placing ``{% render_block "css" %}`` just before the ``</head>`` tag, and and ``{% render_block "js" %}``
+ tag just before the ``</body>``.
+* ``{% cms_toolbar %}`` renders the django CMS toolbar.
@czpython
czpython Dec 31, 2016 Member

should we point out here that this tag cannot be used inside another tag?
or is it somewhere else?

@evildmp
evildmp Jan 3, 2017 Contributor

Now linked to the reference, which does explain this.

docs/how_to/install.rst
-Here is a simple example for a base template called ``base.html``:
+ THUMBNAIL_PROCESSORS = (
@czpython
czpython Dec 31, 2016 Member

I don't think we should be this detailed about django-filer or other dependency installations.
Instead we should just link to them because otherwise we'd have to maintain it here too and the cms docs shouldn't be affected too much from a change in third party apps.

@evildmp
evildmp Jan 3, 2017 Contributor

It's a balancing act - I have removed vast amounts of installation and configuration of dependencies, but kept this because I think not having it would either risk presenting a stumbling block, or significantly reducing the experience of the user.

I added a note to the section to the effect that this is just an example configuration to get the user started.

@coveralls

Coverage Status

Changes Unknown when pulling dad9387 on evildmp:docs-improve-manual-installation into ** on divio:release/3.4.x**.

@coveralls

Coverage Status

Coverage remained the same at 82.598% when pulling dad9387 on evildmp:docs-improve-manual-installation into 386a467 on divio:release/3.4.x.

README.rst
-the details on how to install, extend and use the django CMS.
+We maintain documentation for several versions of the project. Key versions are:
+
+* `stable <http://http://docs.django-cms.org>`_ (default), for the **current release** version
@czpython
czpython Jan 3, 2017 Member

@evildmp looks like another repeated http

@evildmp
evildmp Jan 4, 2017 Contributor

Squashed!

@coveralls

Coverage Status

Coverage remained the same at 82.598% when pulling 3715c79 on evildmp:docs-improve-manual-installation into 5939683 on divio:release/3.4.x.

@evildmp evildmp merged commit 47884a4 into divio:release/3.4.x Jan 4, 2017

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@evildmp evildmp deleted the evildmp:docs-improve-manual-installation branch Jan 4, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment