Elixir + ExDoc

ex_doc.md

Install Erlang

You can use your favorite package manager or please follow this instructions.

https://www.erlang-solutions.com/downloads/download-erlang-otp

Retrieve and compile Elixir

$ mkdir ~/dev
$ cd ~/dev
$ git clone https://github.com/elixir-lang/elixir.git
$ cd elixir 
$ make clean test

Git configuration

$ git config --global user.name "Your Name"
$ git config --global user.email "jdoe@example.com"

Create a fork on GitHub at: https://github.com/elixir-lang/ex_doc

Clone your fork:

$ cd ~/dev
$ git clone https://github.com/<github_username>/ex_doc
$ cd ex_doc
$ git remote add upstream https://github.com/elixir-lang/ex_doc
$ git fetch upstream

Compile ExDoc

$ cd ~/dev/ex_doc && ../elixir/bin/mix do deps.get, compile

How to use ExDoc for build documentation

For example, if we want to build Elixir documentation with ExDoc.

$ cd ~/dev/elixir
$ ../ex_doc/bin/ex_doc "Elixir" "1.1.0-dev" "lib/elixir/ebin" -m "Kernel" -u "https://github.com/elixir-lang/elixir" -o doc -p http://elixir-lang.org/docs.html

The docs can be found below the doc/ directory

Working on a task

Once we know how to use ExDoc to build documentation we can start working on a task

$ cd ~/dev/ex_doc
$ git checkout -b topic_branch upstream/master

Sometimes your mix.lock changes automatically (e.g. if you're working with the master branch of Elixir), avoid to send and updated version of this file, to ignore the local changes on this file you can do the following:

$ git update-index --assume-unchanged mix.lock

Work on your task, add tests if apply, test your changes, etc.

$ git commit -a 

Include a detailed description of your changes, if you're working on a ticket, you should mention it in the commit message, GitHub automatically will put a reference in the ticket that you mentioned once you publish your work.

Create a remote branch and push the changes into it

$ git push origin topic_branch

Create a Pull Request on GitHub!

If you receive some suggestion from the owner or another collaborator of the ExDoc project, you may need to do more commits to adapt your code, if it is the case you should rework the history of your topic branch using the interactive rebase:

$ git rebase -i HEAD~2

The HEAD~2 above is shorthand for two latest commits (can be more). More information about the differences between the options: "pick", "squash", etc. (Normally you'll change the "pick" option on the second line to "squash") here.

If your topic branch is already published at GitHub, you probably will need to force push:

$ git push -f origin topic_branch

If the upstream source has changed in while you are working on a topic branch you should rebase your work doing the following:

$ git fetch upstream
$ git rebase

In case of a conflict you'll need to resolve them using git rebase --continue

If your Pull Request is merged into the master branch you may want to delete your topic_branch, to do this:

$ git checkout master
$ # delete the local branch
$ git branch -d topic_branch
$ # delete the remote branch
$ git push origin :topic_branch 

After changes in ExDoc?

This includes changes on .eex or .ex files.

$ cd ~/dev/ex_doc
$ ../elixir/bin/mix compile

Design changes

I don't know if this is the best approach, but...

Assuming that you have virtualenv installed, then you can install livereload

$ cd ~/dev/elixir
$ virtualenv .env # You need to install first virtualenv (Python)
$ pip install livereload
$ source .env/bin/activate
$ livereload doc/elixir

Then, you can work on the design area with Google Chrome + workspaces

After you confirm all the changes in your workspace, merge those changes into ExDoc.