Sync Turnapi with Git/SVN

Hi Everyone,

First of all I would like to thank all our Beta users who have sent us their opinions, comments and suggestions so far. In several emails, I’ve found the question about our mechanism of synchronization with Git / SVN. This is what I’m going to explain in this post.

I’m going to create documentation for my new project using my favorite text editor, my favorite Git repository and publish everything in my new friend – TurnAPI :) .

1. Creating TurnAPI account

First of all you need to create your own TurnAPI account.

Turnapi signup page

It’s very easy to do. Just log in to http://turnapi.com and  fill in “Sign Up Now” form. A couple seconds and you are in.

TurnAPI will generate initial structure for all new users so that everyone could get up to speed even quicker. Not bad, isn’t it?

I’m going to edit documents locally and store them in my git-repository. In order to do this you’ll need a few  more steps:
1. Open “Manage Versions” page

2. Create a new version of your documentation.

Basically, TurnAPI provides you with two ways of managing API documentation – using website (via web interface) or using your VCS (writing documentation locally in your text editor)

  • Choose “Sync With Git”.
  • Choose version name, e.g. “1.0”
  • Type your Git Read-Only repository path in field “URL”, i use our GitHub account (one of our team members) - git://github.com/alex-hudenko/gitapi.git
  • After that,  you should type a path to the folder with API documentation in field “Path” or leave it empty in case you do not use a separate repo for documentation
Now you are able to remove pre-generated documentation. It was restricted before as we require at least one published version

If you try to open http://gitapi.turnapi.com/ you’ll see something like this – “There are now pages in your top menu now. Please add a couple to continue working on your documentation”

Now everything should be ready to start writing the actual documentation

I’m creating my first page –  “Overview”.

Now i’m adding a new file to git.  Doing commit & push.

cd ~/gitapi/docs

git add Overview.md
git commit -m ‘add Overview page’
git push origin master

Waiting some minutes and testing result

And now we get what the end User sees:

OK, looks not bad, isn’t it? Now i’m going to make “Overview” as a reference tree item and add a few more child’s:

mkdir Overview

mv Overview.md Overview/index.md
touch Overview/Display\ Requirements.md
touch Overview/API\ Terms.md
git commit -a -m ‘add Requirements and Terms’
git push origin master

You should have something like this:

Now i’m adding the content to my pages and pushing the changes:

mkdir Reference

touch Reference/index.md
touch Reference/Overview.md
touch Reference/Search\ API.md
git add Reference/
git commit -m ‘add reference section’

Now i’m adding another section called “Reference” and doing push

If you have not guessed yet, all files with the extension *. md become documents, and all the directories with index.md file inside become sections of your documentation. The title is taken from the file name. All files and folders from the root directory are  first-level sections and show up on the top menu.

Let’s imagine that i need to change documentation order under the section “Overview”. You can do it very easily:

cd Overview/

git mv API\ Terms.md 1-API\ Terms.md
git mv Display\ Requirements.md 2-Display\ Requirements.md
touch Another\ Doc.md
git add Another\ Doc.md
git commit -m ‘order items’
git push origin master

We can also set order (Ascending) for documents adding a number and a dash into their file name (no spaces or zeros) - XX-My Doc.md

By default, documents without numbers are at the end.

It is also very easy to remove useless documents:

git rm Overview.md
git commit -m ‘remove Overview’
git push grid master

Now let’s move “Overview” section and make it sub section of “Reference”

git mv Overview/ Reference/
git commit -m ‘move Overview’
git push origin master

That’s it. As far as you can see it is very easy for any developer to do.

Now a couple of things regarding the problems we have and the things we are working on:

1. Right now you can synchronize with Git using ONLY public repo which is not good. In the nearest future we are going to implement a possibility to exchange keys. In the result synchronization will be private.

2. We’ve implemented only one-way synchronization yet. So, there is no way to change something via web interface and push this back to Git. There are some technical difficulties with implementation of those feature, but we are ready to add them on demand.

 

 

 

Share

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>