From d1ed0cfedb2bf8595032de89410d2a63c5be20ac Mon Sep 17 00:00:00 2001 From: HansBug Date: Tue, 14 Sep 2021 11:16:49 +0800 Subject: [PATCH] doc(hansbug): split docs for numpy.funcs to serverial pages --- docs/source/api_doc/numpy/funcs.rst.py | 73 +++++++++++++++----------- docs/source/api_doc/numpy/index.rst | 2 +- docs/source/api_doc/torch/index.rst | 2 +- treetensor/numpy/funcs.py | 26 +++------ treetensor/torch/funcs.py | 2 +- 5 files changed, 52 insertions(+), 53 deletions(-) diff --git a/docs/source/api_doc/numpy/funcs.rst.py b/docs/source/api_doc/numpy/funcs.rst.py index 4ac8f4303..70aa2f6a3 100644 --- a/docs/source/api_doc/numpy/funcs.rst.py +++ b/docs/source/api_doc/numpy/funcs.rst.py @@ -1,3 +1,4 @@ +import codecs import re import numpy as np @@ -21,34 +22,44 @@ if __name__ == '__main__': print_title(tnp.funcs.__name__, levelc='=') current_module(tnp.funcs.__name__) - for _name in sorted(tnp.funcs.__all__): - _item = getattr(tnp.funcs, _name) - _origin = get_origin(_item) - print_title(_name, levelc='-') - - with print_block('autofunction', value=_name): - pass - - if _origin and (_origin.__doc__ or '').strip(): - with print_block('admonition', value='Numpy Version Related', params={'class': 'tip'}) as f: - print_doc(f""" -This documentation is based on -`numpy.{_name} `_ -in `numpy v{_numpy_version} `_. -**Its arguments\' arrangements depend on the version of numpy you installed**. - -If some arguments listed here are not working properly, please check your numpy's version -with the following command and find its documentation. - -.. code-block:: shell - :linenos: - - python -c 'import numpy as np;print(np.__version__)' - -The arguments and keyword arguments supported in numpy v{_numpy_version} is listed below. - - """, file=f) - print() - - print_doc(_raw_doc_process(_origin.__doc__ or '')) - print() + with print_block('toctree', params=dict(maxdepth=1)) as tf: + for _name in sorted(tnp.funcs.__all__): + _file_tag = f'funcs.{_name}.auto' + _filename = f'{_file_tag}.rst' + print(_file_tag, file=tf) + + _item = getattr(tnp.funcs, _name) + _origin = get_origin(_item) + with codecs.open(_filename, 'w') as sf: + print_title(_name, levelc='=', file=sf) + current_module(tnp.funcs.__name__, file=sf) + + print_title("Documentation", levelc='-', file=sf) + with print_block('autofunction', value=_name, file=sf): + pass + + if _origin and (_origin.__doc__ or '').strip(): + with print_block('admonition', value='Numpy Version Related', + params={'class': 'tip'}, file=sf) as f: + print_doc(f""" + This documentation is based on + `numpy.{_name} `_ + in `numpy v{_numpy_version} `_. + **Its arguments\' arrangements depend on the version of numpy you installed**. + + If some arguments listed here are not working properly, please check your numpy's version + with the following command and find its documentation. + + .. code-block:: shell + :linenos: + + python -c 'import numpy as np;print(np.__version__)' + + The arguments and keyword arguments supported in numpy v{_numpy_version} is listed below. + + """, file=f) + print(file=sf) + + print_title(f"Description For numpy v{_short_version}", levelc='-', file=sf) + print_doc(_raw_doc_process(_origin.__doc__ or ''), file=sf) + print(file=sf) diff --git a/docs/source/api_doc/numpy/index.rst b/docs/source/api_doc/numpy/index.rst index 6072c7d12..9a3149124 100644 --- a/docs/source/api_doc/numpy/index.rst +++ b/docs/source/api_doc/numpy/index.rst @@ -2,7 +2,7 @@ treetensor.numpy ===================== .. toctree:: - :maxdepth: 3 + :maxdepth: 2 funcs.auto numpy.auto diff --git a/docs/source/api_doc/torch/index.rst b/docs/source/api_doc/torch/index.rst index bba292bb6..9fbc6fe13 100644 --- a/docs/source/api_doc/torch/index.rst +++ b/docs/source/api_doc/torch/index.rst @@ -2,7 +2,7 @@ treetensor.torch ===================== .. toctree:: - :maxdepth: 3 + :maxdepth: 2 funcs.auto size.auto diff --git a/treetensor/numpy/funcs.py b/treetensor/numpy/funcs.py index fc14105d0..08cc0eea2 100644 --- a/treetensor/numpy/funcs.py +++ b/treetensor/numpy/funcs.py @@ -1,35 +1,23 @@ import builtins -from typing import List import numpy as np +from treevalue import TreeValue from treevalue import func_treelize as original_func_treelize +from treevalue.utils import post_process from .numpy import TreeNumpy from ..common import ireduce, TreeObject -from ..utils import replaceable_partial, doc_from +from ..utils import replaceable_partial, doc_from, args_mapping __all__ = [ 'all', 'any', 'equal', 'array_equal', ] - -def _doc_stripper(src, _, lines: List[str]): - _name, _version = src.__name__, np.__version__ - _short_version = '.'.join(_version.split('.')[:2]) - return [ - f'.. note::', - f'', - f' This documentation is based on ' - f' `numpy.{_name} `_ ' - f' in `numpy v{_version} `_.', - f' **Its arguments\' arrangements depend on the version of numpy you installed**.', - f'', - *lines, - ] - - -func_treelize = replaceable_partial(original_func_treelize, return_type=TreeNumpy) +func_treelize = post_process(post_process(args_mapping( + lambda i, x: TreeValue(x) if isinstance(x, (dict, TreeValue)) else x)))( + replaceable_partial(original_func_treelize, return_type=TreeNumpy) +) @doc_from(np.all) diff --git a/treetensor/torch/funcs.py b/treetensor/torch/funcs.py index a0f146e1b..8d53b96fc 100644 --- a/treetensor/torch/funcs.py +++ b/treetensor/torch/funcs.py @@ -27,7 +27,7 @@ __all__ = [ ] func_treelize = post_process(post_process(args_mapping( - lambda i, x: Tensor(x) if isinstance(x, (dict, TreeValue)) else x)))( + lambda i, x: TreeValue(x) if isinstance(x, (dict, TreeValue)) else x)))( replaceable_partial(original_func_treelize, return_type=Tensor) ) -- GitLab