Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix missing api-documentation at readthedocs.org #16

Closed
uvchik opened this issue Nov 27, 2015 · 21 comments
Closed

Fix missing api-documentation at readthedocs.org #16

uvchik opened this issue Nov 27, 2015 · 21 comments

Comments

@uvchik
Copy link
Member

uvchik commented Nov 27, 2015

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.

@uvchik uvchik added the bug label Nov 27, 2015
@uvchik uvchik added this to the December 2015 release milestone Nov 27, 2015
@gnn
Copy link
Member

gnn commented Dec 2, 2015

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

@uvchik
Copy link
Member Author

uvchik commented Dec 2, 2015

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
Copy link
Member

gnn commented Dec 2, 2015

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
Copy link
Member

gnn commented Dec 3, 2015

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
Copy link
Member Author

uvchik commented Dec 4, 2015

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
Copy link
Member Author

uvchik commented Dec 4, 2015

@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
Copy link
Member Author

uvchik commented Dec 4, 2015

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

@ckaldemeyer
Copy link
Member

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
Copy link
Member Author

uvchik commented Dec 4, 2015

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
Copy link
Member

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
Copy link
Member

gnn commented Dec 4, 2015

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.

@gnn gnn assigned uvchik and unassigned gnn Dec 4, 2015
@uvchik
Copy link
Member Author

uvchik commented Dec 4, 2015

@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
Copy link
Member

@ckaldemeyer
Copy link
Member

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
Copy link
Member

simnh commented Dec 14, 2015

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
Copy link
Member

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

@ckaldemeyer
Copy link
Member

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

@simnh
Copy link
Member

simnh commented Dec 14, 2015

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
Copy link
Member

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
Copy link
Member Author

uvchik commented Dec 14, 2015

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
Copy link
Member Author

uvchik commented Dec 22, 2015

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants