Praxis makes it easy to generate documentation for your app. To generate documentation:
- create one or more resource definitions
- create one or more associated media types
- invoke the
rake praxis:docs:generate generates JSON documents describing your resource
definitions and media types and writes them to a folder named
your project root.
For example, you may have the following resource definition (along with a suitable Blog media type):
When you run
rake praxis:docs:generate, you will see the generated
documentation in your
docs/api directory. And when you run
praxis:docs:preview, Praxis will start a web server so you can browse the
documentation in a more human-readable format. Point your favorite web browser
to http://localhost:4567 to see it.
Customising the Docs
The default generator will generate a
docs folder for you. In this folder
you can customise the docs output. The docs app that ships with Praxis is a fully
featured documentation browser tool, but chances are that you will want to customise
it’s look and feel before shipping it to customers. The doc browser is built with
Angular.js, Sass and Bootstrap - each of these technologies allowing you to customise
the resulting app. Here are a few ways you can do it, we also have a collection
of recipes on the project wiki.
Changing styles with style.scss
/docs directory you will find a file called
contains a single SASS definition:
Praxis curently runs on Bootstrap. You can customise
all the variables before
this import, and override any styles after it. These will
be recompiled on save and served in the doc browser.
Overriding files through Dependency Injection
/docs directory you will find a file called
app.js which contains
the following code:
This code declares a new module that depends on the provided doc browser. That means that if you provide a provider for any of the services that the doc browser is built on, this will override the one provided by the doc browser itself.
Perhaps you want to add a greeting to the controller section of the app:
Any HTML templates that you put into
docs/views will override templates that
the browser already uses.
Customising via Hooks
Most of the actual documentation content is documentation of various types - the request params type, the request body type, the response headers type, etc.
Each type goes through a template resolver function that decides which view will end up rendering the type. You can add your own resolver function that can return an appropriate template for your type.
For this example, assume that we have defined a custom Set type. In
docs/app.js we do:
Here we register a new resolver function that is dependency injected. There are several special variables you can inject:
$type is the name of the type,
$family is the name of type family this type belongs to (type families provide a generic way to render similar types),
$typeDefinition is an object containing everything we know about the type and finally
$requestedTemplate is one of
Standalone templates exist at a standalone context and take the full width of the page. Embedded templates are for types that exist as a value of a key in a parent type and are rendered in a three column table - they should be one or more
<tr>s. Label templates display the name of a type - which can be a link or conceivably you may add a popover explaining something about your type. Main templates are used for overriding the whole page dedicated to that type.
The resolver function must return one of these possible values:
- a string or a promise of a string: this will be considered a url of a template which will be either requested over http or loaded from the local template cache.
- a link function or a promise of a link function: this will be linked at the appropriate place. Use this if you have a very small template or you want to make some dynamic adjustments to the template. You can get a link function like this:
- undefined: means that this resolver doesn’t know how to handle the type/template combination. This will then invoke the next resolver in the queue. The built-in resolvers are equipped to handle any type (albeit not so well), so they will eventually pick this up.
Shipping the Docs
rake praxis:docs:build. This will create a directory called output,
which has the compressed, offline ready documentation in it. You can then put it into
S3 or GitHub pages or serve them in any other way.