Docstring template

[jnnr]

@FranziPl and @jnnr have extended the docu on GenericCHP and ExtractionTurbineCHP. The aim was the following:

• show the constraints of the components in the oemof-solph part of the docu
• use mathematical symbols that can be understood by the energy community
• show a table that translates between mathematical symbol, meaning and variable name in the code.

These parts have been written to the docstring of the respective Block class of the component

• ExtractionTurbineCHPBlock
• GenericCHPBlock

and are included in the oemof-solph docu.

The purpose of this issue: To keep things consistent, we want to write down a template for this docstring to make it possible to have the same structure for all components.

[jnnr]

class <Some>Block(SimpleBlock): r""" :class:

**The following sets are created:** 

**The following two constraints are created:**

.. _<SomeBlock>-equations:

    .. math::
        <Equations>


========================= ======================== =========
symbol                    explanation              attribute
========================= ======================== =========


========================= ======================== =========

"""

[uvchik]

The main point to discuss is the structure of the equations.

The old equations were (more or less) mathematically exact. In the equations of the ExtractionTurbine the explicit time dependency was removed and the sets.

1. I like the renaming of the variables because it is easier to understand the equations.

2. I would suggest to keep the explicite time dependency: a(t) + b = c(t) instead of `a+b = c (see ExtractionTurbine for a "negative" example and GenericCHP for a positive example).

3. I would suggest to remove the sets because they are not interesting. I would rather list the equations that will be created every time and then add a line: The following constraints will be build if the examp attribute is set (or whatever is the condition to create the constraint): constraints and so on...

[uvchik]

Would be great to have consistent docstrings for v0.3.0.

@oemof/oemof-assistants @oemof/documentation This is not too difficult and good issue for new developer.

[p-snft]

Actually, this is harder than expected. It is not trivial to find what is or should be documented where. Also, not all of the current documentation is perfectly clear to me. (I can work with it, but writing something that others will rely on is a different thing.)

Of course, finding the right symbols is one difficult task, but even when symbols are used, I am not always sure what they mean. Although I am uncertain, I committed something for GenericStorageBlock. For example, I assumed that τ meant the width of the time step (and replaced it by Δt which feels more intuitive to me). A further problem that came up was that some symbols in the equation have no corresponding attribute. This is the case for the aforementioned τ/Δt, but also for the time-dependent capacity which is a variable that is created automatically.

PS: This shows that especially the proposed tables are really needed.

[uvchik]

Could you add this commit to PR #493. It is easier to review there.

[FranziPl]

We disussed part of this issue at the developer meeting in may and I want to ask you about your opinion to our suggestions. We just talked about the docstring of the Block classes. Because of the different natur of the Blocks, we would propose two different kinds of documentation: I) for generic Blocks like Flow and II) for specific ComponentBlocks like ExtractionTurbine.

General recommendations for all Blocks:

• The created sets and subsets should be removed from the docstring.
• The created variables have to be adapted, because they depent on the name of the energysystem, so right now there names are incorrect.
• If there are more than one constraint, they should be numbered.
• time dependency must be integrated (Roght now it is missing for Extraction turbine)
• The order should be harmonized:

1. What is done for all instances of block-class:
   1. The following subsets are created - or leave out generally
   2. The following variables are created
   3. The following constraints are created
2. What is build / done, if a specific attribute is set:
   1. new variables for all block of component
   2. The following constraints are created

Recommendations for the two different kinds of Blocks (general Blocks and Blocks for specific components):

• I) Constraints have to be more generel (like "input"), because it is possible to model a lot of different technologies.
• II) Constrains should be written in a technical/physical way with for example P or Q
  • P and Q must be explained and matched to the attribute in a table like in GenericCHP
  • New order in the table: attribute before explanation
  • Table should contain a new column which shows, what is a parameter and what is a decision variable

I would change the Extraction turbine according to the points, so they will be similar to the GenericCHP. In addition, i will change GenericCHP according to the last points.

[joroeder]

Thanks for the summary! I think this issue is kind of important since it seems that a couple of other issues are related to that (#579 #428 #525 #579 ...).

All together, what do you think about the following template? Did I get everything? (This is independent of option I) or II), because the options will only change the "appearance" of the variables and parameters):

class xyBlock(SimpleBlock):
    r"""Block for the linear relation of nodes with type
        :class:`~oemof.solph.components.xy`

    **The following variables are created:**

        variable_1 :attr:`xy.variable_1[n, t]`
           Description of variable_1 (indexed by XY and TIMESTEPS)

        variable_2 ...

    **The following constraints are created:**

    .. _<SomeBlock>-equations:

    .. math::
        <Equations>
   
    **For the attribute xyz being not None, the following is created:**
    **(Sub)sets:**
        XY_SET
           A set of flows with the attribute...

    **Variable(s):**

        variable_1 ...

    **Constraint(s):**

    .. _<SomeBlock>-equations:

    .. math::
        <Equations>

    **For the attribute uvw being not None, the following is created:**
    **(Sub)sets:**
        UVW_SET
           A set of flows with the attribute...

    **Variable(s):**

        variable_1 ...

    **Constraint(s):**

    .. _<SomeBlock>-equations:

    .. math::
        <Equations>
    """

[FranziPl]

Thanks for the template suggestion. I think, @uvchik said, that we can remove not just the sets, but also the subsets, because it is not necessary? Does anybody use it, without looking them up in the code? Or do I miss something? In addition, I think it matters, if we use Version I) or II), because the table should be part of the template. Apart from that, I agree to your proposal.

[joroeder]

In #522 I have adapted the docstring forthe OffsetTransformer according to option II), see also docstring OffsetTransformerBlock - What do you think?

[FranziPl]

I like it! Two questions: Why did you pick P for the input and output? Why is there "CONSTRAINT_GROUP = True" at the end of the API, as it is after the docstring?

I will change the table of the Generic CHP and than it is similar.

[FranziPl]

A last, more general question: where should the ToDos be? I would put them at the end of the docstring, in the moment, it is inconsistent.

[joroeder]

In addition, I think it matters, if we use Version I) or II), because the table should be part of the template.

Yes, I think as well that the table should be part of "the final" docstring template. Should we put a docstring template in the readthedocs at developing-oemof?

Two questions: Why did you pick P for the input and output?

It is supposed to be the power of a transformer - I changed the explanantion in the docstring table. I also saw, that everybody is using different naming for flow (see docstrings of storage, chp, etc...). I think this comes out if we want to have the option of a more individuel docstring: everybody's naming is different. I think that's okay, because there is always the reference to the flow attribute.

Why is there "CONSTRAINT_GROUP = True" at the end of the API, as it is after the docstring?

I don't know. All block classes of components have it, right?

where should the ToDos be?

I think, we do not need to define that. Because in the end there should be no ToDos left.

[p-snft]

I really like the description of the OffsetTransformerBlock. The idea to distinguish parameters and variables in the table and the use of meaningful symbols really helps reading. Also, removing sets was a good idea. (They are technical details you only need when working with the implementing code - and then you read them in the code anyway.)

Why did you pick P for the input and output?

Typical flows are giving quantities of energy per time, so it is power. I don't know whether I started it, but for me it sounded like the natural choice.

Where should the ToDos be?

In my opinion, they should not be in the documentation at all. They are sometimes used as reminders, but I would consider them a double structure besides the issue management. So, TODOs in the code are easily overseen.

[simnh]

Regarding the Constraint Group: We use the class variable which comes after the docstring and before the methods for some internal processing of constraints. So I think unless we find a better way the get the same functionality (which I did not explain here right now), this will be part of the documentation. It's basically just the way how class variables inside the docs are rendered.

BTW: I really like the new doc style for the components! Great enhancement!

[uvchik]

I created Issue #597 to give an overview which classes need to be adapted to the new template.

@oemof/documentation Shall we add the template to the developer documentation?

[joroeder]

Shall we add the template to the developer documentation?

I think that is a good idea and I could have a try. I am wondering which branch to use? At the moment there is no active branch for docu improvements, right?

[p-snft]

I would suggest to have short living branches from v0.3, so that the changes are easily incorporated into v0.3.1.

[p-snft]

Starting the flows, we are moving to a documentation close to the implementation. So, this template does no longer fit (globally).