Fix doc warnings #287

oyamad · 2017-02-23T05:21:50Z

Unknown sections
- Unknown section Return
- Unknown section Parameters:
- Unknown section Returns:

Example: https://github.com/QuantEcon/QuantEcon.py/blob/master/quantecon/cartesian.py#L16
Change Parameters: to Parameters

The text was updated successfully, but these errors were encountered:

oyamad · 2017-02-23T05:23:45Z

WARNING: Block quote ends without a blank line; unexpected unindent.

/Applications/anaconda/lib/python3.6/site-packages/quantecon/game_theory/mclennan_tourky.py:docstring of quantecon.game_theory.mclennan_tourky.mclennan_tourky:18: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/game_theory/normal_form_game.py:docstring of quantecon.game_theory.normal_form_game.NormalFormGame:10: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/game_theory/normal_form_game.py:docstring of quantecon.game_theory.normal_form_game.Player.best_response:6: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/game_theory/normal_form_game.py:docstring of quantecon.game_theory.normal_form_game.Player.best_response:17: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/game_theory/normal_form_game.py:docstring of quantecon.game_theory.normal_form_game.Player.best_response:34: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/game_theory/normal_form_game.py:docstring of quantecon.game_theory.normal_form_game.Player.payoff_vector:12: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/game_theory/random.py:docstring of quantecon.game_theory.random.covariance_game:24: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/game_theory/random.py:docstring of quantecon.game_theory.random.random_game:17: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/markov/core.py:docstring of quantecon.markov.core.MarkovChain.is_aperiodic:0: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/markov/core.py:docstring of quantecon.markov.core.MarkovChain.num_recurrent_classes:3: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/markov/core.py:docstring of quantecon.markov.core.MarkovChain.recurrent_classes:0: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/markov/core.py:docstring of quantecon.markov.core.mc_sample_path:27: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/markov/ddp.py:docstring of quantecon.markov.ddp.DiscreteDP.operator_iteration:12: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/markov/ddp.py:docstring of quantecon.markov.ddp.DiscreteDP.operator_iteration:13: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/markov/random.py:docstring of quantecon.markov.random.random_discrete_dp:45: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/markov/random.py:docstring of quantecon.markov.random.random_markov_chain:27: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/markov/random.py:docstring of quantecon.markov.random.random_stochastic_matrix:26: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/markov/random.py:docstring of quantecon.markov.random.random_stochastic_matrix:31: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/random/utilities.py:docstring of quantecon.random.utilities.probvec:20: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/random/utilities.py:docstring of quantecon.random.utilities.sample_without_replacement:24: WARNING: Block quote ends without a blank line; unexpected unindent.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/compute_fp.py:docstring of quantecon.compute_fp.compute_fixed_point:57: WARNING: Block quote ends without a blank line; unexpected unindent.

oyamad · 2017-02-23T05:25:20Z

WARNING: Inline * start-string without end-string.

/Applications/anaconda/lib/python3.6/site-packages/quantecon/markov/ddp.py:docstring of quantecon.markov.ddp.DiscreteDP:85: WARNING: Inline substitution_reference start-string without end-string.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/quad.py:docstring of quantecon.quad.quadrect:13: WARNING: Inline emphasis start-string without end-string.
/Applications/anaconda/lib/python3.6/site-packages/quantecon/quad.py:docstring of quantecon.quad.quadrect:13: WARNING: Inline strong start-string without end-string.

mmcky · 2017-02-23T05:29:36Z

Thanks @oyamad. This is helpful. I will add a review of readthedocs to my list.

mmcky · 2017-02-23T05:45:21Z

The page:

http://quanteconpy.readthedocs.io/en/latest/game_theory/lemke_howson.html

doesn't seem to be bringing the docstring through.

http://quanteconpy.readthedocs.io/en/latest/game_theory/mclennan_tourky.html
http://quanteconpy.readthedocs.io/en/latest/game_theory/pure_nash.html
http://quanteconpy.readthedocs.io/en/latest/game_theory/support_enumeration.html

on readthedocs

oyamad · 2017-02-23T06:01:03Z

And this page:
http://quanteconpy.readthedocs.io/en/latest/game_theory/utilities.html

Also this page has not been updated:
http://quanteconpy.readthedocs.io/en/latest/tools/compute_fp.html

oyamad · 2017-02-23T06:13:40Z

These pages display the docstrings locally on my machine.

oyamad · 2017-02-23T06:20:23Z

I guess this line has to be updated.

Does any process update this file rtd-environment.yml automatically?

mmcky · 2017-02-23T06:36:37Z

This is looking better: http://quanteconpy.readthedocs.io/en/rtd-env-update/
Once it passes tests I will merge to fix missing pages.

oyamad · 2017-02-23T06:45:28Z

Very good.

What is the difference between "stable" and "latest"? I thought "stable" is from the released version and "latest" from master, but it seems not the case.

mmcky · 2017-02-23T06:47:27Z

we just had the same thought :). I am looking into that now in the rtd setup. I agree. I think stable should be the latest release and latest should be master.

mmcky · 2017-02-23T06:58:32Z

ah ha. So the adjustments we've made to documentation isn't contained in 0.3.4 so the stable won't reflect those changes as it is in the pre-updated state. I will disable stable for now in rtd and then we can fix this by issuing a new release 0.3.5.

oyamad · 2017-02-23T07:12:10Z

latest is showing the released 0.3.4 rather than master. Is this what you expect?

mmcky · 2017-02-23T07:18:19Z

latest is building 7cc7943ad3dff8755e70c61f6964d70901366c0e which is the last commit on master. Am I missing something?

oyamad · 2017-02-23T07:28:49Z

For example, in http://quanteconpy.readthedocs.io/en/latest/game_theory/lemke_howson.html:
Functions other than lemke_howson are private functions, to which _ have been added on master, so they should not show up in the documentation.

Do we really need the - quantecon entry in the - pip list in rtd-environment.yml? Wouldn't RTD run python setup.py install without it?

oyamad · 2017-02-23T12:59:12Z

See #291 where setup_py_install: true is added to readthedocs.yml.

mmcky · 2017-02-23T22:05:36Z

Another task

review latex code throughout documentation site for proper rendering, new lines etc. [Assign to QuantEcon RA during early March workshop]

Some of this has now been addressed:

fix missing documentation from pages above
review warning information from readthedocs

shizejin · 2017-02-24T13:10:52Z

The Warning message Block quote ends without a blank line; unexpected unindent. could be solved by adding a new line between the type and description of parameters, e.g.

random_state : scalar(int) or np.random.RandomState,
                   optional(default=None)
        Random seed (integer) or np.random.RandomState instance to set
        the initial state of the random number generator for
        reproducibility. If None, a randomly initialized RandomState is
        used.

to

random_state : scalar(int) or np.random.RandomState,
                   optional(default=None)

        Random seed (integer) or np.random.RandomState instance to set
        the initial state of the random number generator for
        reproducibility. If None, a randomly initialized RandomState is
        used.

But I don't know if it's a proper way, as usually there is no such empty line in most of docstrings.

mmcky · 2017-02-26T00:49:59Z

Hi @shizejin. Thanks for looking into this issue. According to numpydoc style guide, having no space is preferred. I will take a closer look at autodoc to see why this warning is getting raised and get back to you.

oyamad · 2017-02-26T08:01:38Z

The problem is that the list of parameter types is too long that

def random_game(nums_actions, random_state=None):
    """
    ...

    Parameters
    ----------
    ...

    random_state : scalar(int) or np.random.RandomState, optional(default=None)

would exceed the maximum line length 72 for docstrings.

One option is to shorten the description to

    random_state : int or np.random.RandomState, optional(default=None)

or

    random_state : scalar(int) or np.random.RandomState, optional

shizejin · 2017-02-26T08:23:11Z

It seems that docs of Numpy are using the latter one, and declare the default value in the detailed descriptions of parameters. Should I apply this modification to the files with warning messgaes?

oyamad · 2017-02-26T08:29:21Z

What are the other cases that yield the unexpected unindent warning?

shizejin · 2017-02-26T11:56:50Z

I have checked all the Block quote ends without a blank line; unexpected unindent. warning message, and they are all in this case.

shizejin · 2017-02-26T12:25:29Z

Other than these warnings, the only one left is /quantecon/markov/ddp.py:docstring of quantecon.markov.ddp.DiscreteDP:85: WARNING: Inline substitution_reference start-string without end-string.

* Transition probabilities q(s'|s, a):

q(0|0, 0) = 0.5, q(1|0, 0) = 0.5,
q(0|0, 1) = 0,   q(1|0, 1) = 1,
q(0|1, 0) = 0,   q(1|1, 0) = 1

And this is caused by using s'. As it is not appropriate to bracket it with "`", maybe we could replace it with another expression?

oyamad · 2017-02-26T12:49:53Z

@shizejin Will you change all the s' in the docstring of DiscreteDP (lines 121-284) and in solve (line 651) to s_next (and keep the others)? Thanks!

oyamad · 2017-02-26T12:52:48Z

There is one more in compute_fp.py.

Please change

    method : str in {'iteration', 'imitation_game'},
             optional(default='iteration')
        Method of computing an approximate fixed point

to

    method : str in {'iteration', 'imitation_game'}, optional
        Method of computing an approximate fixed point
        (default='iteration')

oyamad · 2017-02-26T12:56:50Z

Regarding random_state:

Please change

    random_state : scalar(int) or np.random.RandomState,
                   optional(default=None)

to

    random_state : int or np.random.RandomState, optional(default=None)

(I think this looks better.)

shizejin · 2017-02-26T14:20:48Z

Changes have been done.

Other than cases that can be solved by changing scalar(int) to int and optional(default=None) to optional, there are two types of Block quote ends without a blank line; unexpected unindent. warning messgaes left.

In ddp.py and random.py, with long sets, e.g.

method : str in {'value_iteration', 'vi', 'policy_iteration',
                     'pi', 'modified_policy_iteration', 'mpi'},
            optinal(default='policy_iteration')
            Solution method.

In normal_form_game.py,

    data : array_like(Player) or array_like(int, ndim=1) or
           array_like(float, ndim=2 or N+1)

How to deal with these?

mmcky · 2017-02-26T22:14:24Z

Hey @shizejin and @oyamad. Just letting you know I am running some setup workshops today for some new QuantEcon RA's. So I won't get to look into this issue until tomorrow (most likely). I wonder if there is a numpydoc linter that we can use? It might be a useful approach to catch these errors in the editor.

oyamad · 2017-03-10T15:06:32Z

@shizejin

Please change

        method : str in {'value_iteration', 'vi', 'policy_iteration',
                         'pi', 'modified_policy_iteration', 'mpi'},
                 optinal(default='policy_iteration')
            Solution method.

to

        method : str, optinal(default='policy_iteration')
            Solution method, str in {'value_iteration', 'vi',
            'policy_iteration', 'pi', 'modified_policy_iteration',
            'mpi'}.

and

    format : str in {'bsr', 'csr', 'csc', 'coo', 'lil', 'dia', 'dok'},
             optional(default='csr')
        Sparse matrix format. Relevant only when sparse=True.

to

    format : str, optional(default='csr')
        Sparse matrix format, str in {'bsr', 'csr', 'csc', 'coo', 'lil',
        'dia', 'dok'}. Relevant only when sparse=True.

Change

    data : array_like(Player) or array_like(int, ndim=1) or
           array_like(float, ndim=2 or N+1)

to

    data : array_like of Player, int (ndim=1), or float (ndim=2 or N+1)

Thanks!

shizejin · 2017-03-12T05:45:04Z

Sure. I have done these changes.

Also, in the normal_form_game.py, I change

        opponents_actions : array_like(int or array_like(float)) or
                            array_like(int, ndim=1) or scalar(int)

to

        opponents_actions : array_like(int or array_like(float)) or int

I omit "array_like(int, ndim=1)" as I think it is included in "array_like(int or array_like(float))", and otherwise I can not shorten the sentence to be under 79. Do you think this change is acceptable?

Now that there is no any warning message, I will do PR if you think it's okay.

oyamad · 2017-03-14T14:59:47Z

"array_like(int, ndim=1)" should have been "array_like(float, ndim=1)".
The maximum line length is 72 for docstrings, if we want to strictly follow PEP 8.

What about just

        opponents_actions : scalar(int) or array_like

shizejin · 2017-03-14T15:31:18Z

Looks concise and accurate. Should I do PR based on this?

oyamad mentioned this issue Feb 23, 2017

DOC: Generate doc files for game_theory #286

Merged

mmcky self-assigned this Feb 23, 2017

mmcky added bug invalid and removed bug invalid labels Feb 23, 2017

shizejin mentioned this issue Feb 24, 2017

WIP: fix doc warnings #292

Merged

oyamad assigned mmcky and unassigned mmcky Feb 24, 2017

mmcky closed this as completed in #292 Mar 19, 2017

oyamad mentioned this issue Aug 24, 2017

Option to supply a random seed #153

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix doc warnings #287

Fix doc warnings #287

oyamad commented Feb 23, 2017

oyamad commented Feb 23, 2017

oyamad commented Feb 23, 2017

mmcky commented Feb 23, 2017

mmcky commented Feb 23, 2017

oyamad commented Feb 23, 2017

oyamad commented Feb 23, 2017

oyamad commented Feb 23, 2017

mmcky commented Feb 23, 2017

oyamad commented Feb 23, 2017

mmcky commented Feb 23, 2017

mmcky commented Feb 23, 2017

oyamad commented Feb 23, 2017

mmcky commented Feb 23, 2017 •

edited

Loading

oyamad commented Feb 23, 2017

oyamad commented Feb 23, 2017

mmcky commented Feb 23, 2017 •

edited

Loading

shizejin commented Feb 24, 2017

mmcky commented Feb 26, 2017

oyamad commented Feb 26, 2017

shizejin commented Feb 26, 2017

oyamad commented Feb 26, 2017

shizejin commented Feb 26, 2017

shizejin commented Feb 26, 2017

oyamad commented Feb 26, 2017

oyamad commented Feb 26, 2017

oyamad commented Feb 26, 2017

shizejin commented Feb 26, 2017

mmcky commented Feb 26, 2017

oyamad commented Mar 10, 2017

shizejin commented Mar 12, 2017

oyamad commented Mar 14, 2017

shizejin commented Mar 14, 2017

Fix doc warnings #287

Fix doc warnings #287

Comments

oyamad commented Feb 23, 2017

oyamad commented Feb 23, 2017

oyamad commented Feb 23, 2017

mmcky commented Feb 23, 2017

mmcky commented Feb 23, 2017

oyamad commented Feb 23, 2017

oyamad commented Feb 23, 2017

oyamad commented Feb 23, 2017

mmcky commented Feb 23, 2017

oyamad commented Feb 23, 2017

mmcky commented Feb 23, 2017

mmcky commented Feb 23, 2017

oyamad commented Feb 23, 2017

mmcky commented Feb 23, 2017 • edited Loading

oyamad commented Feb 23, 2017

oyamad commented Feb 23, 2017

mmcky commented Feb 23, 2017 • edited Loading

shizejin commented Feb 24, 2017

mmcky commented Feb 26, 2017

oyamad commented Feb 26, 2017

shizejin commented Feb 26, 2017

oyamad commented Feb 26, 2017

shizejin commented Feb 26, 2017

shizejin commented Feb 26, 2017

oyamad commented Feb 26, 2017

oyamad commented Feb 26, 2017

oyamad commented Feb 26, 2017

shizejin commented Feb 26, 2017

mmcky commented Feb 26, 2017

oyamad commented Mar 10, 2017

shizejin commented Mar 12, 2017

oyamad commented Mar 14, 2017

shizejin commented Mar 14, 2017

mmcky commented Feb 23, 2017 •

edited

Loading

mmcky commented Feb 23, 2017 •

edited

Loading