EPx/Energyplus Documentation!

[Clayton Miller]

First off, I'm very excited about EPx and the development vision that it has.

To get things off on good footing, I want to share an inspiration that Jacob Kaplan-Moss (one of the lead developers of Django) communicated to me at PyCon Asia last year - Good documentation is one of the most important components of an open source project.  You can check out the same presentation I saw on video, slidedeck, or his mantra on his blog.

Along those lines, I want to initiate discussion towards how we can do this with EPx - using Sourceforge? an open source html documentation generator such as Sphynx? Can the existing Energyplus pdf documentation be ported to html? Do we even want to do that?

[Clayton Miller]

I propose: www.readthedocs.org

Took me 30 seconds to create: http://energyplus.readthedocs.org/en/latest/

[Neal Kruis]

This is great! and definitely in line with where we would like to move the EPx project!

Ultimately, as mentioned on the EPx website, we want to "Convert documentation to text-based source files that can be stored in the repository and compiled into PDF and HTML documents; add hyperlink references between related object classes; post documentation on a web site."

It looks like Read the Docs with Sphynx provides all of this capability. There may be other tools available as well that may be worth considering.

As we choose a tool there are also a few other problems we need to address:

Current EnergyPlus documentation is in PDF documents generated from MS Word. We are working on bringing the original documentation source into the shared EPx repository. 

The way I see it, we will have find a way to convert documentation (including all of the figures, tables, and equations) from the .doc files as they are released with canonical versions of EnergyPlus and manage merging changes from new canonical releases with any fixes/updates made to the EPx documentation.

Any ideas?

[Clayton Miller]

How does one get access to the .doc EnergPlus documentation? I'd like to play around with some conversion approaches.

Are there any copyright issues with publishing the documentation independently? I would guess that it would be the same policy as the source code...

[Peter Ellis]

The EnergyPlus documentation "source" files--a collection of Word documents--are not included with the zip files that are published as the open-source version by the EnergyPlus team on the special collaborative developer/open-source site.  I'm not sure what the intention was, but we can't assume that either the documentation source (which we don't have) or even the PDF format is covered by the open-source license since it's not included with the open-source distribution.  Therefore we are not even able to redistribute the existing EnergyPlus PDF docs.

I've been in touch with the DOE program manager for EnergyPlus about this and he's indicated they will work on releasing the documentation source as part of the open-source distro.

I should also note that there are a number of other pieces of the end-user release distribution, besides the documentation, that are not included in the open-source distribution.  This includes the example input files and the source code for all of the auxiliary programs.  Hopefully DOE can release as much of that as possible under the open-source license too.

P

--
You received this message because you are subscribed to the Google Groups "EPx Developers" group.
To post to this group, send email to epx-dev...@googlegroups.com.
To unsubscribe from this group, send email to epx-developer...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msg/epx-developers/-/XOY62E1bD9kJ.

For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Clayton Miller]

Perhaps we just need written permission to reproduce the documentation in html format (similar to any other piece of copyrighted material)? Maybe a simple email from the DOE stating that its ok for our documentation purposes would be sufficient? I can't imagine there would be resistance to empowering better use of EnergyPlus.

To post to this group, send email to epx-developers@googlegroups.com.
To unsubscribe from this group, send email to epx-developers+unsubscribe@googlegroups.com.