CNAME for pgRoutingLayer documentation

[cvvergara]

Talking with @cayetanobv, he wants to use (I forgot the name of the thing) on gh-pages of pgRoutingLayer in order to have the documentation there. he mentions that (what ever the name is, remember i forgot the name of the thing) is easy to use with code coming from python and pgRoutingLayer is python code.

Maybe you can add a CNAME file for pgRoutingLayer.pgRouting.org just like the one it has on pgrouting https://github.com/pgRouting/pgrouting/blob/gh-pages/CNAME

So that we can start on the documentation of v3.0.0 of pgRoutingLayer that use python3

[dkastl]

@cvvergara @cayetanobv , I find pgroutinglayer.pgrouting.org doesn't look like a good URL. Who wants to type that? ;-)

What about qgis.pgrouting.org? I can still make a redirect from the long version.

[dkastl]

FYI, we do not need gh-pages branch anymore. Github settings now allow to select any branch (for example master) and a subdirectory for hosting the static website: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/

[cayetanobv]

Thanks @dkastl . I've uploaded a preview of the documentation to my github pgRoutingLayer page so you can see how it works. These documents are NOT UPDATED (they are only a test for you to see my proposal). I prepared all this docs in 10 minutes :)

Link: https://cayetanobv.github.io/pgRoutingLayer/ (only for testing purpose...).

The tool I propose to use is Mkdocs (https://www.mkdocs.org/), a tool widely used in the Python world. It is very simple to use and the time it takes to update documentation is minimal. Everyone knows how to write Markdown, so there is no excuse if someone wants to collaborate :)

In this branch (in my repository) I pushed all required files: https://github.com/cayetanobv/pgRoutingLayer/tree/new_documentation

You only need to write documentation in this folder in Markdown format (it is so easy): https://github.com/cayetanobv/pgRoutingLayer/tree/new_documentation/docs

and prepare the mkdocs YAML file: https://github.com/cayetanobv/pgRoutingLayer/blob/new_documentation/mkdocs.yml

The deployment is also very easy and simple; Steps:

• Install mkdocs CLI: pip install mkdocs
• you can run this simple script to build and upload docs to github pages.

As @dkastl says we can configure any branch to upload docs, but I think is better to upload to a separate branch (like gh-pages) because the only interesting files we need in branch master are markdown files (prebuild files). I think we don't want in branch master all post-build files (css, js, etc.).

Thanks,

[cayetanobv]

... I forgot to say I'm using Readthedocs theme but we can use another.

[dkastl]

hmm, on one side I understand, that built documentation doesn't need to be in master branch. On the other side I found it quite inconvenient with the workshop for example, that two branches are different content.

That's why I initially thought, it would be nice to have the docs in Markdown, because then source would be all we need, and Github would care about compiling it. And at the same time Markdown can be read without being compiled in Github repository view for example.

Your approach is a bit like Sphinx, just using a different tool.

Well, in the end I would leave this up to the person, who actually maintains the documentation ;-)

[cayetanobv]

Yes, It is a very similar approach but I like mkdocs because I think we can go faster. The goal is to spend more time coding or documenting and less time with deploys and related things.

If we want to publish docs of several branches at the same time we need to think how to do it.

By the way I approved https://github.com/pgRouting/pgRoutingLayer/pull/83

[dkastl]

FYI, I have made the Github settings to use the /docs folder for testing purpose of the custom domain settings, mainly because gh-pages branch does not exist yet. This should be easy to change, when it's there.

[cayetanobv]

Ok @dkastl