Fix missing api-documentation at readthedocs.org

[uvchik]

I would like to get it work within the next week, to make it easier to read the docstrings.

@gnn : If you do not feel responsible, reassign it to me.

[gnn]

We figured out the problem.
Looks like until readthedocs/readthedocs.org#1139 is fixed, we have to commit apidocs by hand.

[uvchik]

I added the api folder and fix small things in the setup.py. Now readthedocs (RTD) is able to compile the API-docs. This works only for the dev-branch. You have to merge the dev-branch into all branches you want to see at RTD.

@oemof/oemof-main : Please check if your docstrings are correct.

http://oemof-base.readthedocs.org/en/dev/

RTD cannot install shapely due to a missing c-library (geos). I have no idea how to fix it but at the moment it will be a problem of oemof_pg rather than oemof_base.

Running Shapely-1.5.13/setup.py -q bdist_egg --dist-dir /tmp/easy_install-7zi_60xe/Shapely-1.5.13/egg-dist-tmp-avj1k2_2
Failed `CDLL(libgeos_c.so.1)`
Failed `CDLL(libgeos_c.so)`
error: Could not find library geos_c or load any of its variants ['libgeos_c.so.1', 'libgeos_c.so']

[gnn]

I have an idea. Since generating the documentation doesn't really call into the library but only has to resolve the imports, one could create mockups of the modules to make Sphinx think the modules exist and are already imported. I'll see whether I'll get around to doing this tomorrow.

[gnn]

I see the build passes and oemof_pg isn't on RTD yet. Do we want to close this issue and make a new one in oemof_pg to add oemof_pg's docs to RTD and fix their build process there?

[uvchik]

I'm glad it works for oemof_base and I just added oemof_pg to RTD.
But the api doesn't work. I fixed the api docs on pvlib and oemof_base but it is so annoying that it never works out of the box 😞 .

It is a good idea to add an issue at oemof_pg's github page. I will try to fix it before Christmas. Or will you fix it?

[uvchik]

@oemof/oemof-main : The dev branch is now readable at readthedocs. Please check your code if it looks as expected and give a feedback. If everything looks right we can close this issue.

[uvchik]

Just for sure: http://oemof-base.readthedocs.org/en/dev/

[ckaldemeyer]

I have fixed some typos and added a figure "framework concept" as svg-graphics which worked locally. Can you rebuild and check if everything also works on RTD?

[uvchik]

I build is done. If you do have an account on RTD I could add you to the repository there, so that you can start the builds yourself.

[ckaldemeyer]

Looks good: http://oemof-base.readthedocs.org/en/dev/meta_description.html

At least in my browser..

I have just signed on readthedocs.org. My username is "ckaldemeyer". Thanks!

[gnn]

I created issue oemof/oemof-db#2 for the missing apidocs there. I'll handle it. I already know how to solve issues occurring because of needed packages which can't be installed in RTD, so I'm going to fix this before christmas.
Also, since I'm no only responsible for the oemof/oemof_pg related problems, I'm going to reassign this to you @uvchik cause I don't think there's anything left to be done for me here.

[uvchik]

@gnn Thanks. If your oemof_base docs appear at RTD as they should, you are done with this issue.

@simonhilpert , @caro-rli , @cswh please check your docstrings.

[ckaldemeyer]

http://www.pythonhosted.org/oemof_base/meta_description.html

[ckaldemeyer]

The latest documentation is still from the dev-branch and does not include the fixes in the meta-description. Should we merge back into the master?

[simnh]

if its a fix merge the features/meta-description branch in master and dev. don't merge dev into master, as this would be a release (our workflow)

[ckaldemeyer]

It was directly on the dev-branch. So should I create a new release branch now?

[ckaldemeyer]

Or a hotfix-branch. And then merge from the release/hotfix into the master.. ?!

[simnh]

as we will have a release soon (22), maybe we can start a release branch at the end of the week or even now already

[ckaldemeyer]

sounds reasonable. we should just keep it in mind for the next release then. i guess not that many people are reading the oemof documentatio so far ;)

[uvchik]

I would like the "latest" flag to point on the dev-branch but it is not possible. Or we have to rename the master to stable and use the master less strictly. But this might be a difficult discussion....

[uvchik]

Everything seems to work. If you find a problem, please open a special issue.