So you’ve read all the introductory material and have decided you’d like to keep using Server. 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 Server’s documentation useful, easy to read 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.)
Server’s got a lot of documentation – almost 450,000 words and counting – so finding what you need can sometimes be tricky. A few good places to start are the Search Page and the Index.
Or you can just browse around!
Server’s main documentation is broken up into “chunks” designed to fill different needs:
The introductory material is designed for people new to Server – or to Web development in general. It doesn’t cover anything in depth, but instead gives a high-level overview of how developing in Server “feels”.
The topic guides, on the other hand, dive deep into individual parts of Server. There are complete guides to Server’s model system, template engine, forms framework, 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 Server.
Web development is often broad, not deep – problems span many domains. We’ve written a set of how-to guides that answer common “How do I …?” questions. Here you’ll find information about generating PDFs with Server, writing custom template tags, and more.
Answers to really common questions can also be found in the FAQ.
The guides and how-to’s don’t cover every single class, function, and method available in Server – that would be overwhelming when you’re trying to learn. Instead, details about individual classes, functions, methods, and modules are kept in the reference. 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 several guides for various deployment setups as well as a deployment checklist for some things you’ll need to think about.
Finally, there’s some “specialized” documentation not usually relevant to most developers. This includes the release notes and internals documentation for those who want to add code to Server itself, and a few other things that simply don’t fit elsewhere.
Just as the Server code base is developed and improved on a daily basis, our documentation is consistently improving. We improve documentation for several reasons:
Server’s documentation is kept in the same source control system as its code. It lives in the docs directory of our Git repository. Each document online is a separate text file in the repository.
You can read Server documentation in several ways. They are, in order of preference:
The most recent version of the Server documentation lives at https://docs.serverproject.com/en/dev/. These HTML pages are generated automatically from the text files in source control. That means they reflect the “latest and greatest” in Server – they include the very latest corrections and additions, and they discuss the latest Server features, which may only be available to users of the Server development version. (See Differences between versions below.)
We encourage you to help improve the docs by submitting changes, corrections and suggestions in the ticket system. The Server developers actively monitor the ticket system and use your feedback to improve the documentation for everybody.
Note, however, that tickets should explicitly relate to the documentation, rather than asking broad tech-support questions. If you need help with your particular Server setup, try the server-users mailing list or the #server IRC channel instead.
For offline reading, or just for convenience, you can read the Server documentation in plain text.
If you’re using an official release of Server, 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 Server (aka the master 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
Server document:
$ grep -r max_length /path/to/server/docs/
...\> grep -r max_length \path\to\server\docs\
You can get a local copy of the HTML documentation following a few easy steps:
Server’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:
$ python -m pip install Sphinx
...\> py -m pip install Sphinx
Then, just use the included Makefile to turn the documentation into
HTML:
$ cd path/to/server/docs
$ make html
You’ll need GNU Make installed for this.
If you’re on Windows you can alternatively use the included batch file:
cd path\to\server\docs
make.bat html
The HTML documentation will be placed in docs/_build/html.
The text documentation in the master branch of the Git repository contains the “latest and greatest” changes and additions. These changes include documentation of new features targeted for Server’s next feature release. For that reason, it’s worth pointing out our policy to highlight recent changes and additions to Server.
We follow this policy:
May 04, 2019