Create documentation infrastructure

[katcipis]

I started building a documentation infrastructure.

Mkdocs seems to be a good choice, so I started with it here:

https://github.com/NeowayLabs/neosearch/tree/addingDocsInfra

Sadly, for some reason, it should map the 8000 port when you run make docs and you should be able to checkout the doc, but right know it is not working (on netstat you can see that something is getting stuck on the 8000 port...but it does not work).

Also, I still cant integrate html documentation with the rest of the docs (the godocs documentation for example)

Mkdocs has github pages integration, perhaps is a interesting way to deploy the documentation.

[katcipis]

Ok, integrating with HTML is quite stupid since it generates a static site :P. I was confused because I was checking out the wrong site folder and was not finding the html files.

Now it integrates with godoc, but it is not pretty :-(

Also, make docs should show docs on your browser using sensible-browser command, still dont know why port mapping + mkdocs serve is not working :-(

[i4ki]

:)

Very nice !!!

I'd tested here, and the only problem that I found was the "sensible-browser" command on the Makefile. My Linux distro doesn't have this program. Replacing "sensible-browser" by "xdg-open" can be a better portability way of invoke the default browser.

What do you think?

About the docs, we can use the GitHub site generator to render the docs in neosearch.github.io domain?

[katcipis]

xdg-open worked like a charm ;-)

I think we could use the neosearch.github.io, mkdocs gh-pages should do all the heavy lifting for us.

Can you test if mkdocs serve works for you ? For some kind of reason it is not working here. I think it would be even better than using xdg-open. In the last case...we leave as it is now.

I want to integrate swagger on all this too, so we can start to document the REST API properly

[katcipis]

Swagger integration is close :-). Just need to start defining the API. I separated the docs Dockerfile from the dev, installing java on the dev Dockerfile felt wrong :-P

[katcipis]

Done :-)