Creating an app guide in Griffon

Since Griffon 0.9, the documentation engine that powers the creation of the Griffon guide is available to all Griffon projects.

It's a really helpful tool and very easy to use. You should complete your documentation toolbox with this one.

To create your own guide you have to create first a directory hierarchy. Inside your Griffon project under the src directory, just create one directory called docs:



The docs directory should have at least the guide directory, and optionally you can create the img directory, this directory is where the guide images are searched by default.

Once we have the documentation structure, we have to create the different chapters of our guide. The classification depends on the file name convention. As you can see in the picture:



We have three chapters. So this way the name of the file is made up from the chapter number plus a point plus an space and the name of chapter, and finally it should have the suffix of a gdoc file.

Now we are going to focus on the file "2. Listing Tweets.gdoc" and what can we write inside? Well Griffon documentation (Chapter 3.5) is plenty of examples about the syntax of this kind of documents . Here is the content of this file:

To list your HomeLine tweets just click Tweets-> Refresh

!refresh.png!

If haven't login to twitter a login/password dialog will appear.
Just enter your data, then the login button will be enabled.

!login.png!

If the credentials were right you will see your tweet
list and a message box to create more tweets.

!list.png!

As I told there are many options concerning the syntaxis of our documents, but here I want to highlight the use of the images in our documents. If we just put our image files in the src/docs/guide/imgs we can reference them just by their names, like I do in the previous example.



Once we have finished our documents, just go to command line and in the project's directory write:

griffon doc

Right now in the documentation says to use "griffon docs" but it's wrong. Fortunately the Griffon command line shows you the alternatives, so you will see the doc option anyway

If everything goes right you will see something like this:






This way we can create the user guide while we're creating our application.

• Griffon project
  


• Griffon guide