datacollection histogram docstring format

[mostaphaRoudsari]

[chriswmackey]

@saeranv , As the author of this method, can you take care of this? It looks like your use of the code-block is not properly formatted.

[saeranv]

@chriswmackey, yes, I can fix this.

[saeranv]

I thought the error was that I had the usage tag in the wrong location, and so copied the other code::usage blocks exactly, but looks like the docs are still not interpreting this correctly.

Let me look up the autodocumentation documentation and send another PR

[saeranv]

@chriswmackey

Might need your help on this. After checking the sphinx docs, SO, and going through my PR - I can't find anything that I'm doing wrong.

Here's what I'm submitting as a code-block:

    @staticmethod
    def histogram(values, bins, hist_range=None, key=None):
        """Compute the frequency histogram from a list of values.

        The data is binned inclusive of the lower bound but exclusive of the upper bound
        for intervals. See usage for example of losing the last number in the following
        dataset because of exclusive upper bound.

        Args:
            values: Set of numerical data as a list.
            bins: A monotonically increasing array of uniform-width bin edges, excluding
                the rightmost edge.
            hist_range: Optional parameter to define the lower and upper range of the
                histogram as a tuple of numbers. If not provided the range is
                ``(min(key(values)), max(key(values))+1)``.
            key: Optional parameter to define key to bin values by, as a function. If not
                provided the histogram will be binned by the value.

        Returns:
            A list of lists representing the ordered values binned by frequency.
               ``histogram([0, 1, 1, 2, 3], [0, 2, 3]) -> [[0, 1, 1], [2]]``

        Usage:

        .. code-block:: python
            from BaseCollection import histogram

            # Simple example
            histogram([0, 0, 0.9, 1, 1.5, 1.99, 2, 3], (0, 1, 2, 3))
            # >> [[0, 0, 0.9], [1, 1.5, 1.99], [2]]

            # With key parameter
            histogram(
                zip([0, 0, 0.9, 1, 1.5, 1.99],
                    ['a', 'b', 'c', 'd', 'e', 'f']),
                    (0, 1, 2), key=lambda k: k[0])
            # >> [[(0, 'a'), (0, 'b'), (0.9, 'c')], [(1, 'd'), (1.5, 'e'), (1.99, 'f')]]
        """

Versus this working example:

    @staticmethod
    def compute_function_aligned(funct, data_collections, data_type, unit):
        """Compute a function with a list of aligned data collections or individual values.

        Args:
            funct: A function with a single numerical value as output and one or
                more numerical values as input.
            data_collections: A list with a length equal to the number of arguments
                for the function. Items of the list can be either Data Collections
                or individual values to be used at each datetime of other collections.
            data_type: An instance of a Ladybug data type that describes the results
                of the funct.
            unit: The units of the funct results.

        Return:
            A Data Collection with the results function. If all items in this list of
            data_collections are individual values, only a single value will be returned.

        Usage:

        .. code-block:: python

            from ladybug.datacollection import HourlyContinuousCollection
            from ladybug.epw import EPW
            from ladybug.psychrometrics import humid_ratio_from_db_rh
            from ladybug.datatype.percentage import HumidityRatio

            epw_file_path = './epws/denver.epw'
            denver_epw = EPW(epw_file_path)
            pressure_at_denver = 85000
            hr_inputs = [denver_epw.dry_bulb_temperature,
                         denver_epw.relative_humidity,
                         pressure_at_denver]
            humid_ratio = HourlyContinuousCollection.compute_function_aligned(
                humid_ratio_from_db_rh, hr_inputs, HumidityRatio(), 'fraction')
            # humid_ratio will be a Data Colleciton of humidity ratios at Denver

All spaces, spelling, and indents are the same. Why isn't the documentation working for mine?

[mostaphaRoudsari]

You need one empty line after .. code-block::python line:

        Usage:

        .. code-block:: python
            from BaseCollection import histogram

should be:

        Usage:

        .. code-block:: python

            from BaseCollection import histogram