=================
What to read next
=================

So you've read all the :doc:`introductory material </intro/index>` and have
decided you'd like to keep using GingerDJ. We've only just scratched the surface
with this intro (in fact, if you've read every single word, you've read about
5% of the overall documentation).

So what's next?

Well, we've always been big fans of learning by doing. At this point you should
know enough to start a project of your own and start fooling around. As you need
to learn new tricks, come back to the documentation.

We've put a lot of effort into making GingerDJ's documentation useful, clear and
as complete as possible. The rest of this document explains more about how the
documentation works so that you can get the most out of it.

(Yes, this is documentation about documentation. Rest assured we have no plans
to write a document about how to read the document about documentation.)

Finding documentation
=====================

GingerDJ's got a *lot* of documentation -- almost 450,000 words and counting --
so finding what you need can sometimes be tricky. A good place to start
is the :ref:`genindex`. We also recommend using the builtin search feature.

Or you can just browse around!

How the documentation is organized
==================================

GingerDJ's main documentation is broken up into "chunks" designed to fill
different needs:

* The :doc:`introductory material </intro/index>` is designed for people new
  to GingerDJ -- or to web development in general. It doesn't cover anything
  in depth, but instead gives a high-level overview of how developing in
  GingerDJ "feels".

* The :doc:`topic guides </topics/index>`, on the other hand, dive deep into
  individual parts of GingerDJ. There are complete guides to GingerDJ's
  :doc:`model system </topics/db/index>`, :doc:`template engine
  </topics/templates>`, :doc:`forms framework </topics/forms/index>`, and much
  more.

  This is probably where you'll want to spend most of your time; if you work
  your way through these guides you should come out knowing pretty much
  everything there is to know about GingerDJ.

* Web development is often broad, not deep -- problems span many domains.
  We've written a set of :doc:`how-to guides </howto/index>` that answer
  common "How do I ...?" questions. Here you'll find information about
  :doc:`generating PDFs with GingerDJ </howto/outputting-pdf>`, :doc:`writing
  custom template tags </howto/custom-template-tags>`, and more.

  Answers to really common questions can also be found in the :doc:`FAQ
  </faq/index>`.

* The guides and how-to's don't cover every single class, function, and
  method available in GingerDJ -- that would be overwhelming when you're
  trying to learn. Instead, details about individual classes, functions,
  methods, and modules are kept in the :doc:`reference </ref/index>`. This is
  where you'll turn to find the details of a particular function or
  whatever you need.

* If you are interested in deploying a project for public use, our docs have
  :doc:`several guides</howto/deployment/index>` for various deployment
  setups as well as a :doc:`deployment checklist</howto/deployment/checklist>`
  for some things you'll need to think about.


How documentation is updated
============================

Just as the GingerDJ code base is developed and improved on a daily basis, our
documentation is consistently improving. We improve documentation for several
reasons:

* To make content fixes, such as grammar/typo corrections.

* To add information and/or examples to existing sections that need to be
  expanded.

* To document GingerDJ features that aren't yet documented. (The list of
  such features is shrinking but exists nonetheless.)

* To add documentation for new features as new features get added, or as
  GingerDJ APIs or behaviors change.

GingerDJ's documentation is kept in the same source control system as its code. It
lives in the :source:`docs` directory of our Git repository. Each document
online is a separate text file in the repository.

Where to get it
===============

You can read GingerDJ documentation in several ways. They are, in order of
preference:

On the web
----------

The most recent version of the GingerDJ documentation lives at
https://www.gingersociety.org/products/ginger-dj/docs/


In plain text
-------------

For offline reading, or just for convenience, you can read the GingerDJ
documentation in plain text.

If you're using an official release of GingerDJ, the zipped package (tarball) of
the code includes a ``docs/`` directory, which contains all the documentation
for that release.

If you're using the development version of GingerDJ (aka the main branch), the
``docs/`` directory contains all of the documentation. You can update your
Git checkout to get the latest changes.

One low-tech way of taking advantage of the text documentation is by using the
Unix ``grep`` utility to search for a phrase in all of the documentation. For
example, this will show you each mention of the phrase "max_length" in any
GingerDJ document:

.. console::

    $ grep -r max_length /path/to/gingerdj/docs/

As HTML, locally
----------------

You can get a local copy of the HTML documentation following a few steps:

* GingerDJ's documentation uses a system called Sphinx__ to convert from
  plain text to HTML. You'll need to install Sphinx by either downloading
  and installing the package from the Sphinx website, or with ``pip``:

  .. console::

        $ python -m pip install Sphinx

* Then, use the included ``Makefile`` to turn the documentation into HTML:

  .. code-block:: console

        $ cd path/to/gingerdj/docs
        $ make html

  You'll need `GNU Make`__ installed for this.

  If you're on Windows you can alternatively use the included batch file:

  .. code-block:: bat

        cd path\to\gingerdj\docs
        make.bat html

* The HTML documentation will be placed in ``docs/_build/html``.

__ https://www.sphinx-doc.org/
__ https://www.gnu.org/software/make/

