Check static documentation files

[cswh]

• Check static documentation files
• Is it complete?
• What has to be done?
• File issues for the work which still has to be done.

[uvchik]

I don't like the first section title: "Meta description". For me it is an introduction or a description but "meta" makes no sense for me. Just if you apply changes anyway.

[uvchik]

Please set a realistic milestone. Use the comments to make the progress transparent.

[uvchik]

@cswh : You can watch this repository at github to get the comments and new issues by e-mail.

[cswh]

Sorry I got lost in too many issue notifications. Will be done with the January Release.

[simnh]

Is this still possible for the january release? or should we reset the milestone?

[ckaldemeyer]

@uvchik : Should we change "Meta description" to "General description" or something similar?

Another thing: Is the framework-concept figure (http://www.pythonhosted.org/oemof_base/meta_description.html) displayed correctly in your browsers? I just see "alternate text" instead and the file (http://www.pythonhosted.org/oemof_base/_images/framework_concept.svg) is not shown. I thought this was working in a former release..

[uvchik]

The figure works on readthedocs. http://oemof-base.readthedocs.org/en/latest/meta_description.html#open-energy-system-modeling-framework-oemof

I would call it "Overview", "Introduction" or "General Description". Feel free.

[ckaldemeyer]

I like "Overview" and will change it on the dev..

Another proposal: I don't like the position of "Documentation" in the hierachy and would place it under "The solph package".

[ckaldemeyer]

The figure works on readthedocs. http://oemof-base.readthedocs.org/en/latest/meta_description.html#open-energy-system-modeling-framework-oemof

But all links point to Pythonhosted. We should fix it there. But I don't understand why it's not working there. Does it use a different configuration of sphinx?

@gnn : do you have an idea?

[uvchik]

Pythonhosted is build once we do the release. I did it for the last release and didn't notice it did not work. Now the release manager is responsible for the compilation of the documentation. So it is a different person every time.

One idea is to set two persons in charge for the documentation, who know how to do it.

Another idea is to create an overview page with a link to the RTD documentation.

Or we do not use the link at all, but I think it is not bad to have our name spread over different server.

[ckaldemeyer]

Or we do not use the link at all, but I think it is not bad to have our name spread over different server.

Indeed, this would be an option for me. Redundant structures always require additional work and "advertising" works via papers, presentations, mailing lists and websites.

[ckaldemeyer]

Or are there any other purposes than the advertisement one?

[uvchik]

Search engines. But we can create an version independent text with a link to the RTD documentaton.

[ckaldemeyer]

+1

[ckaldemeyer]

I doubt the search engine argument since it at least contradicts googles PageRank. But your proposal with the version independent link sounds good and should give us a higher ranking!

What about something like:

" Open Energy Modelling Framework (oemof) - A modular open source framework to model energy supply systems

More information can be found here: http://oemof-base.readthedocs.org/en/latest/ " By the way I have changed "Meta description" to "Overview" and also changed the file name and the reference in the rst-index".

[uvchik]

By the way I have changed "Meta description" to "Overview" and also changed the file name and the reference in the rst-index".

Thank you. I will write a short text and upload it to pythonhosted within the next days or maybe today.

[uvchik]

By the way. Pythonhosted is the second entry searching oemof using google.

[ckaldemeyer]

Thank you. I will write a short text and upload it to pythonhosted within the next days or maybe today. Thanks!

[ckaldemeyer]

By the way. Pythonhosted is the second entry searching oemof using google.

We just have to make sure that all links (from opendmod, etc.) point to one place to get readthedocs on google #2 or #1 ;-)

[uvchik]

I added a static file at https://pythonhosted.org/oemof/. I is not too nice so feel free to edit it.

I also created a new readthedocs page at http://oemof.readthedocs.org/. It points to http://oemof.readthedocs.org/en/stable/ which points to the latest release (now: http://oemof.readthedocs.org/en/v0.0.3/). If you want to get the latest developer documentation you get it at http://oemof.readthedocs.org/en/latest (uses the dev-branch).

@oemof/oemof-main : Is it okay for you?

[ckaldemeyer]

I found one error "Get the omeof documentations of the latest release" and think it's o.k. for a first shot.

@uvchik : How can I edit the entry?

The rest looks good to me. Thanks for you effort!!!

[uvchik]

@uvchik : How can I edit the entry?

Download, edit, create a zip-folder and upload again.

Download

wget https://pythonhosted.org/oemof/index.html
wget https://pythonhosted.org/oemof/oemof_big.png

Structure of the zip-folder

some_name.zip
|_index.html
|_oemof_big.png

[cswh]

So far, no urgent matter anymore. But we will have a deeper look on the static documentations again on the 4th Developer Meeting.

[cswh]

Perhaps the pythonhosted infos should move to wiki?

[ckaldemeyer]

I have added it to the release-documentation: https://github.com/oemof/oemof/wiki/How-to-release

[uvchik]

You do not have to do this all the time. By default pypi keeps the actual documentation.

[ckaldemeyer]

I know. You're right with the wrong position in the How-to-release page. It's now a single page under "Misc": https://github.com/oemof/oemof/wiki