Natural Docs + GitHub Pages = online auto-documentation for free (almost)

GitHub has a funny thing called GitHub Pages .

Can be used in two ways - you can either muddle the site, or make docks to the repository, the manual is written in detail about this.

We are not interested in the site now, but the docks to the repository are the topic of what we need. For example, I will use the project in javascript, but this is not important, Natural Docs supports a decent pack of languages, which is good.

So, we need NaturalDocs itself - we go, we swing , we put, we look at examples.
')
Plus, we need to create a standard new project on GitHub. Understand that yes how. For example, let's call it My New Cool Project (you can use the existing one, but it’s better to train on new cats ).

Without long shelving, we immediately start pages , like this:

cd My-New-Cool-Project
git symbolic-ref HEAD refs/heads/gh-pages
rm .git/index
git clean -fdx
echo "My GitHub Page" > index.html
git add .
git commit -a -m "First pages commit"
git push origin gh-pages

In the process there will be funny inscriptions that something is removed there - this is normal :)

Try to visit the page http: // username .github.com / My-New-Cool-Project /, where instead of username we set our login.

In theory, we should get a clean page labeled “My GitHub Page” in the upper left corner. There is? Great, moving on.

Let's do the code and documentation.

First check where we go back to master brunch

git status

if the beginning looks like this

# On branch gh-pages

doing

git co master

Ok, now in the project branch in the master branch we will create the following structure:

mkdir lib
mkdir doc
mkdir nd_internal

The first is the directory for our code, the second is the place where the documentation will be stored, the latter is needed for NaturalDocs

Nb. best after creation to bring the nd_internal folder from under git - in the .git / info / exclude file add a new line nd_internal / *

Now we write some code, accompanying it with comments in the style of NaturalDocs (in the lib folder).

Well, we put the code with the comments we have, we will need to explain to NaturalDocs what we want. It is required to write something like the following:

naturaldocs -i ./lib/ -o HTML ./doc/ -p ./nd_internal/

Where naturaldocs is the name of your NaturalDocs executable file, it may differ from the one given, you will understand.

If everything went well, you will see something like:

Finding files and detecting changes...
Parsing 1 file...
Building 1 file...
Building 2 indexes...
Updating CSS file...
Done.

Try to open the index.html file from the doc directory - you should get a beautiful documentation page.

Now we will commit all the changes, but for the time being we don’t push anything (if the docks have been generated, and nothing has changed on the site, we forgot to commit before the next step).

After the commit, we need a bit of magic - a detailed explanation of what is happening and what is happening is written by Dominic Mitchell in his article Publishing a subdirectory to github pages , if you 're interested, go there. I'll just give an example of my script:

#!/bin/bash

doc_dir='doc' # document directory
tmp_message='tmp_mess' # temporary files for changelog message
gh_pages='refs/heads/gh-pages' # refs to pages

parent_sha=$(git show-ref -s $gh_pages)
doc_sha=$(git ls-tree -d HEAD $doc_dir | awk '{print $3}')
git log --pretty=format:'%s' -n 1 $doc_dir > $tmp_message
new_commit=$(git commit-tree $doc_sha -p $parent_sha < $tmp_message )
rm $tmp_message
git update-ref $gh_pages $new_commit

echo "Docs update done"

In theory, everything should have gone well and we received an update of documents in the gh-pages branch.

Now is the time to do

git push

In response, we should have something like this:

Counting objects: 24, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (12/12), done.
Writing objects: 100% (13/13), 1.26 KiB, done.
Total 13 (delta 5), reused 0 (delta 0)
To git@github.com:Meettya/My-New-Cool-Project.git
f0005ad..a53b950 gh-pages -> gh-pages
48b901d..f0b787e master -> master

The important thing in this is the last two lines, there should be two commits in both branches.

And now we go to http: // username .github.com / My-New-Cool-Project / and check if everything is in place. In theory, we should see our wonderful documentation.

Now nothing prevents you from making a link to our docks in the README file and get a profit from automated documenting of the code.

My test project, which can be twisted for how and what has been done - jQuery Enhance Library . There you can find examples of docks and all scripts as well as an example of NaturalDocs syntax.