Documentation Setup

This is how I setup the project blog for this document. If you create your own mobile-first project based on this repository, you can simply add or replace items in these docs to your liking. Then you won’t need to setup the orphaned gh-pages branch.

If you’d like to setup docs / notes (blog) within your application then you might find this helpful.

Settup

This blog uses sphinx-docs and ablog, just as http://blog.readthedocs.com now does.

I setup a virtualenv in the docs direectory, and:

$ pip install -r requirements.txt

then activate the environment when working on docs.

To set your docs to appear as project github pages, a separate output directory was made for sphin-docs, named (in this case) after the repository, mobile-first.

To make this output directory hold the rendered documentation, first make sure it does not exist in the docs area.

Then, make a git-submodule to the main directory, thus:

$ git submodule add -b gh-pages git@github.com:yarko/mobile-first.git ./docs/mobile-first

where mobile-first (repository and target) is replaced with your repository name. This makes the repository a git-submodule to itself. Now, similarly as shown on https://help.github.com/articles/creating-project-pages-manually, do the following:

$ cd docs/mobile-first
$ git checkout --orphan gh-pages
$ git rm -rf .
# Note: the new branch won't appear in the branch list until your first commit
$ touch .nojekyll

You’ll notice in the Makefile (under the build command), mobile-first is the output directory. Modify your Makefile to output to your sphinx-docs output directory.

Now:

$ make build
$ git add --all
$ git commit -a -m 'first ablog build to gh-pages'
# the first time, set the default upstream, so we can 'git push` from here on
$ git push --set-upstream origin gh-pages

Give it a few minutes, then you should be able to navigate to your equivalent path of http://{{your-github-account}}.github.io/{{your-project-repository}}, e.g. http://yarko.github.io/mobile-first.

After this initial step, you should be able to simply edit an entry, and then:

$ make build    # to compile the html
$ make show     # to see the output locally
# Then, once you're happy, commit the source; then:
$ make publish  # to commit & push the generated results

and view your results at your equivalent of http://yarko.github.io/mobile-first.

Feel free to file an issue.

  Device Layout