Document all functions and add full reference of the calculation procedure

[jimenofonseca]

For every function make sure it is documented and it has a reference to a standard or a paper inside the code. @daren-thomas will do some magic to extract this information and put it nicely in a website (see #463)

[jimenofonseca]

I would suggest the next division of branches and scripts for each one to work on:

i464-demand-docs: All the files and subfolders included in cea/demand, except subfolder of calibration. @gabriel-happle .

i464-analysis: all the files included in cea/analysis. except that of sensitivity. @martin-mosteiro

i464-calibration-sensitivity: All the files included in cea/demand/calibration @me.

i464-databases: All files included in cea/databases. @me

i464-optimization: All the files included in cea/optimization. @BhargavaKrishnaSreepathi .

i464-technologies-resources: All the files included in cea/technologies and cea/resources @shanshanhsieh

[jimenofonseca]

The next is an example of a well documented function: @daren-thomas please let me know if that is the case or modify)

def properties(locator, prop_thermal_flag, prop_architecture_flag,
               prop_hvac_flag, prop_comfort_flag, prop_internal_loads_flag, gv):
    """
    This function queries building properties from a statistical database
    of archetypes. These building properties are then assigned to every building of the
    case study. The database and calculation procedure are described
    in Fonseca et al. 2015. Integrated Model for characterisation of spatio-temporal
    building energy demand. Appl. energy.

    Parameters
    ----------
    :param InputLocator locator: an InputLocator instance set to the scenario to work on
    :param boolean prop_thermal_flag: if True, get properties about thermal properties of the building envelope.
    :param boolean prop_architecture_flag: if True, get properties about the construction and architecture.
    :param boolean prop_hvac_flag: if True, get properties about types of HVAC systems, otherwise False.
    :param GlobalVariables gv: an instance of globalvar.GlobalVariables with the constants  to use
        (like `list_uses` etc.)
    Side effects:
    -------------
    The following files are created by this script, depending on which flags were set:
    - building_HVAC: .shp
        describes the queried properties of HVAC systems.
    - building_architecture: .shp
        describes the queried properties of architectural features
    - building_thermal: .shp
        describes the queried thermal properties of buildings
    - building_comfort: .shp
        describes the queried thermal properties of buildings
    - building_loads: .shp
        describes the queried thermal properties of buildings
    """

    # get occupancy and age files
    building_occupancy_df = gpdf.from_file(locator.get_building_occupancy()).drop('geometry', axis=1)
    list_uses = list(building_occupancy_df.drop(['PFloor','Name'], axis=1).columns) #parking excluded in U-Values
    building_age_df = gpdf.from_file(locator.get_building_age())

    # prepare shapefile to store results (a shapefile with only names of buildings
    fields_drop = ['envelope', 'roof', 'windows', 'partitions', 'basement', 'HVAC', 'built']  # FIXME: this hardcodes the field names!!
    names_shp = gpdf.from_file(locator.get_building_age()).drop(fields_drop, axis=1)

    # define main use:
    building_occupancy_df['mainuse'] = calc_mainuse(building_occupancy_df, list_uses)

[daren-thomas]

Check here for the syntax of the :param notation: http://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html

It seems you want to do something along the lines of

:param locator: an InputLocator instance set to the scenario to work on
:type locator: InputLocator

That is, separate :param: and :type:. Also, you can specify :returns: and :rtype:.

This information can then be processed by Sphynx for building the documentation (I am currently learning Sphynx...)

[jimenofonseca]

Current status:

i464-databases: 80% done! - described in gitbook i464-optimization: Done! - inserted in the code

[jimenofonseca]

Current status:

i464-databases: done! - described in gitbook i464-optimization: Done! - inserted in the code

@martin-mosteiro @shanshanhsieh @gabriel-happle what is the status on this?

[shanshanhsieh]

Update to the technologies part: Three technologies: radiators.py, controllers.py, heating_coils.py related to the demand scripts, will need support from @gabriel-happle. The solar radiation related scripts (photovoltaic.py, photovoltaic_thermal.py,solar_collector) are unchanged, since it will be updated after issue #336 is merged. The substation.py is unchanged, will be updated when branch i412 is merged. Missing information in other scripts is listed in issue #478 .

[jimenofonseca]

@shanshanhsieh great!, for what is left of your part would you mind creating an issue so we can get rid of this one. what about @gabriel-happle and @martin-mosteiro ?

[gabriel-happle]

@JIMENOFONSECA I was waiting for the merge of my branch. I believe most of the new stuff is documented. I will have a look at the new assignment by @shanshanhsieh . But for me it is not clear which documentation we are actually going for... Daren Version from above or Jimeno Version from above?

[martin-mosteiro]

@JIMENOFONSECA 85% done, I'll finish it up after the meeting