Summary
Follow-up from #850 (raised by @oyamad). #850 moved the base-level tools API pages to document the public objects in the quantecon namespace (e.g. quantecon.ARMA instead of quantecon._arma.ARMA / quantecon.arma.ARMA). The subpackage pages still document objects by their internal file module, so they render the internal module segment.
Example: markov/core.html shows
class quantecon.markov.core.MarkovChain(P, state_values=None)
but MarkovChain is re-exported at the package level (quantecon/markov/__init__.py), so ideally it should read
class quantecon.markov.MarkovChain(P, state_values=None)
The same applies across game_theory.*, optimize.*, random.*, and util.*, which the generator documents via automodule:: quantecon.<pkg>.<file>.
Proposed fix
Apply the same treatment qe_apidoc.py now uses for the base-level pages, one level down: for each subpackage page use .. currentmodule:: quantecon.<pkg> plus explicit autoclass / autofunction directives for the objects that file defines and that are re-exported at quantecon.<pkg>. Page structure can stay as-is (one page per internal file); only the directive/heading changes.
Scope
Roughly 30 file-pages and ~66 objects across five subpackages:
| Package |
Re-exported at quantecon.<pkg>.* |
Defined in files but not re-exported |
| markov |
15 |
2 |
| game_theory |
38 |
3 |
| optimize |
13 |
1 |
| random |
(small) |
— |
| util |
(small) |
— |
Dependency on #853
The "not re-exported" objects in the right column are the same class of problem as #853 (objects reachable only via an internal module, not the public package namespace). This work should be gated on the #853 decision (promote to the package namespace / document via the internal module / omit) so the same rule is applied consistently across the whole API reference, rather than converting the subpackages under a different policy.
Priority
Non-blocking (per @oyamad on #850). Best done as a dedicated follow-up PR once #853 is resolved. Related: #850, #853.
Summary
Follow-up from #850 (raised by @oyamad). #850 moved the base-level tools API pages to document the public objects in the
quanteconnamespace (e.g.quantecon.ARMAinstead ofquantecon._arma.ARMA/quantecon.arma.ARMA). The subpackage pages still document objects by their internal file module, so they render the internal module segment.Example: markov/core.html shows
but
MarkovChainis re-exported at the package level (quantecon/markov/__init__.py), so ideally it should readThe same applies across
game_theory.*,optimize.*,random.*, andutil.*, which the generator documents viaautomodule:: quantecon.<pkg>.<file>.Proposed fix
Apply the same treatment
qe_apidoc.pynow uses for the base-level pages, one level down: for each subpackage page use.. currentmodule:: quantecon.<pkg>plus explicitautoclass/autofunctiondirectives for the objects that file defines and that are re-exported atquantecon.<pkg>. Page structure can stay as-is (one page per internal file); only the directive/heading changes.Scope
Roughly 30 file-pages and ~66 objects across five subpackages:
quantecon.<pkg>.*Dependency on #853
The "not re-exported" objects in the right column are the same class of problem as #853 (objects reachable only via an internal module, not the public package namespace). This work should be gated on the #853 decision (promote to the package namespace / document via the internal module / omit) so the same rule is applied consistently across the whole API reference, rather than converting the subpackages under a different policy.
Priority
Non-blocking (per @oyamad on #850). Best done as a dedicated follow-up PR once #853 is resolved. Related: #850, #853.