Fix the Errors/Warnings when building Qlib's documentation (microsoft…

…#1381) * Fix the Errors/Warnings when building Qlib's documentation * Fix * Fix * Empty * Test CI * Add doc compiling checking to CI * Fix * Tries to be consistent with Makefile Co-authored-by: you-n-g <you-n-g@users.noreply.github.com>
AIGeniusInstitute · Dec 5, 2022 · 5b73b80 · 5b73b80
1 parent 6a47416
commit 5b73b80
Show file tree

Hide file tree

Showing 26 changed files with 127 additions and 78 deletions.
diff --git a/.github/workflows/test_qlib_from_source.yml b/.github/workflows/test_qlib_from_source.yml
@@ -60,7 +60,7 @@ jobs:
     - name: Make html with sphinx
       run: |
         cd docs 
-        sphinx-build -b html . build
+        sphinx-build -W --keep-going -b html . _build
         cd ..
 
     # Check Qlib with pylint

diff --git a/docs/Makefile b/docs/Makefile
@@ -17,4 +17,5 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
+	pip install -r requirements.txt
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/reference/api.rst b/docs/reference/api.rst
@@ -117,7 +117,7 @@ Model
 Strategy
 --------
 
-.. automodule:: qlib.contrib.strategy.strategy
+.. automodule:: qlib.contrib.strategy
     :members:
 
 Evaluate
@@ -255,7 +255,7 @@ Utils
 Serializable
 ------------
 
-.. automodule:: qlib.utils.serial.Serializable
+.. automodule:: qlib.utils.serial
     :members:
 
 RL

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -4,3 +4,4 @@ numpy
 scipy
 scikit-learn
 pandas
+tianshou
diff --git a/qlib/contrib/evaluate.py b/qlib/contrib/evaluate.py
@@ -96,9 +96,11 @@ def indicator_analysis(df, method="mean"):
         index: Index(datetime)
     method : str, optional
         statistics method of pa/ffr, by default "mean"
+
         - if method is 'mean', count the mean statistical value of each trade indicator
         - if method is 'amount_weighted', count the deal_amount weighted mean statistical value of each trade indicator
         - if method is 'value_weighted', count the value weighted mean statistical value of each trade indicator
+
         Note: statistics method of pos is always "mean"
 
     Returns
@@ -154,6 +156,7 @@ def backtest_daily(
         E.g.
 
         .. code-block:: python
+
             # dict
             strategy = {
                 "class": "TopkDropoutStrategy",
@@ -180,7 +183,6 @@ def backtest_daily(
             # 3) specify module path with class name
             #     - "a.b.c.ClassName" getattr(<a.b.c.module>, "ClassName")() will be used.
 
-
     executor : Union[str, dict, BaseExecutor]
         for initializing the outermost executor.
     benchmark: str

diff --git a/qlib/contrib/report/analysis_model/analysis_model_performance.py b/qlib/contrib/report/analysis_model/analysis_model_performance.py
@@ -276,8 +276,8 @@ def model_performance_graph(
 ) -> [list, tuple]:
     """Model performance
 
-    :param pred_label: index is **pd.MultiIndex**, index name is **[instrument, datetime]**; columns names is **[score,
-    label]**. It is usually same as the label of model training(e.g. "Ref($close, -2)/Ref($close, -1) - 1").
+    :param pred_label: index is **pd.MultiIndex**, index name is **[instrument, datetime]**; columns names is **[score, label]**.
+           It is usually same as the label of model training(e.g. "Ref($close, -2)/Ref($close, -1) - 1").
 
 
             .. code-block:: python

diff --git a/qlib/contrib/report/analysis_position/cumulative_return.py b/qlib/contrib/report/analysis_position/cumulative_return.py
@@ -218,6 +218,7 @@ def cumulative_return_graph(
 
 
         Graph desc:
+
             - Axis X: Trading day.
             - Axis Y:
             - Above axis Y: `(((Ref($close, -1)/$close - 1) * weight).sum() / weight.sum()).cumsum()`.
@@ -242,7 +243,8 @@ def cumulative_return_graph(
 
 
     :param label_data: `D.features` result; index is `pd.MultiIndex`, index name is [`instrument`, `datetime`]; columns names is [`label`].
-    **The label T is the change from T to T+1**, it is recommended to use ``close``, example: `D.features(D.instruments('csi500'), ['Ref($close, -1)/$close-1'])`
+
+        **The label T is the change from T to T+1**, it is recommended to use ``close``, example: `D.features(D.instruments('csi500'), ['Ref($close, -1)/$close-1'])`
 
 
             .. code-block:: python

diff --git a/qlib/contrib/report/analysis_position/rank_label.py b/qlib/contrib/report/analysis_position/rank_label.py
@@ -99,7 +99,8 @@ def rank_label_graph(
 
     :param position: position data; **qlib.backtest.backtest** result.
     :param label_data: **D.features** result; index is **pd.MultiIndex**, index name is **[instrument, datetime]**; columns names is **[label]**.
-    **The label T is the change from T to T+1**, it is recommended to use ``close``, example: `D.features(D.instruments('csi500'), ['Ref($close, -1)/$close-1'])`.
+
+        **The label T is the change from T to T+1**, it is recommended to use ``close``, example: `D.features(D.instruments('csi500'), ['Ref($close, -1)/$close-1'])`.
 
 
             .. code-block:: python

diff --git a/qlib/contrib/strategy/cost_control.py b/qlib/contrib/strategy/cost_control.py
@@ -25,12 +25,14 @@ def __init__(
         common_infra=None,
         **kwargs,
     ):
-        """Parameter
+        """
+        Parameters
+        ----------
         topk : int
             top-N stocks to buy
         risk_degree : float
-            position percentage of total value
-            buy_method :
+            position percentage of total value buy_method:
+
                 rank_fill: assign the weight stocks that rank high first(1/topk max)
                 average_fill: assign the weight to the stocks rank high averagely.
         """
@@ -51,12 +53,19 @@ def get_risk_degree(self, trade_step=None):
         return self.risk_degree
 
     def generate_target_weight_position(self, score, current, trade_start_time, trade_end_time):
-        """Parameter:
-        score : pred score for this trade date, pd.Series, index is stock_id, contain 'score' column
-        current : current position, use Position() class
-        trade_date : trade date
-        generate target position from score for this date and the current position
-        The cache is not considered in the position
+        """
+        Parameters
+        ----------
+        score:
+            pred score for this trade date, pd.Series, index is stock_id, contain 'score' column
+        current:
+            current position, use Position() class
+        trade_date:
+            trade date
+
+            generate target position from score for this date and the current position
+
+            The cache is not considered in the position
         """
         # TODO:
         # If the current stock list is more than topk(eg. The weights are modified

diff --git a/qlib/contrib/strategy/signal_strategy.py b/qlib/contrib/strategy/signal_strategy.py
@@ -103,9 +103,13 @@ def __init__(
             before sell stock , will check current.get_stock_count(order.stock_id) >= self.hold_thresh.
         only_tradable : bool
             will the strategy only consider the tradable stock when buying and selling.
+
             if only_tradable:
+
                 strategy will make decision with the tradable state of the stock info and avoid buy and sell them.
+
             else:
+
                 strategy will make buy sell decision without checking the tradable state of the stock.
         """
         super().__init__(**kwargs)
@@ -287,9 +291,11 @@ def __init__(
             the decision of the strategy will base on the given signal
         trade_exchange : Exchange
             exchange that provides market info, used to deal order and generate report
+
             - If `trade_exchange` is None, self.trade_exchange will be set with common_infra
             - It allowes different trade_exchanges is used in different executions.
             - For example:
+
                 - In daily execution, both daily exchange and minutely are usable, but the daily exchange is recommended because it run faster.
                 - In minutely execution, the daily exchange is not usable, only the minutely exchange is recommended.
         """
@@ -303,6 +309,7 @@ def __init__(
     def generate_target_weight_position(self, score, current, trade_start_time, trade_end_time):
         """
         Generate target position from score for this date and the current position.The cash is not considered in the position
+
         Parameters
         -----------
         score : pd.Series
@@ -355,12 +362,14 @@ class EnhancedIndexingStrategy(WeightStrategyBase):
 
     Users need to prepare their risk model data like below:
 
-    ├── /path/to/riskmodel
-    ├──── 20210101
-    ├────── factor_exp.{csv|pkl|h5}
-    ├────── factor_cov.{csv|pkl|h5}
-    ├────── specific_risk.{csv|pkl|h5}
-    ├────── blacklist.{csv|pkl|h5}  # optional
+    .. code-block:: text
+
+        ├── /path/to/riskmodel
+        ├──── 20210101
+        ├────── factor_exp.{csv|pkl|h5}
+        ├────── factor_cov.{csv|pkl|h5}
+        ├────── specific_risk.{csv|pkl|h5}
+        ├────── blacklist.{csv|pkl|h5}  # optional
 
     The risk model data can be obtained from risk data provider. You can also use
     `qlib.model.riskmodel.structured.StructuredCovEstimator` to prepare these data.

diff --git a/qlib/data/cache.py b/qlib/data/cache.py
@@ -141,8 +141,10 @@ def __init__(self, mem_cache_size_limit=None, limit_type="length"):
 
         Parameters
         ----------
-        mem_cache_size_limit: cache max size.
-        limit_type: length or sizeof; length(call fun: len), size(call fun: sys.getsizeof).
+        mem_cache_size_limit:
+            cache max size.
+        limit_type:
+            length or sizeof; length(call fun: len), size(call fun: sys.getsizeof).
         """
 
         size_limit = C.mem_cache_size_limit if mem_cache_size_limit is None else mem_cache_size_limit
@@ -858,7 +860,7 @@ def gen_dataset_cache(self, cache_path: Union[str, Path], instruments, fields, f
         """gen_dataset_cache
 
         .. note:: This function does not consider the cache read write lock. Please
-        Acquire the lock outside this function
+            acquire the lock outside this function
 
         The format the cache contains 3 parts(followed by typical filename).
 
@@ -874,10 +876,10 @@ def gen_dataset_cache(self, cache_path: Union[str, Path], instruments, fields, f
                     1999-11-12 00:00:00     2   3
                     ...
 
-            .. note:: The start is closed. The end is open!!!!!
+                .. note:: The start is closed. The end is open!!!!!
 
             - Each line contains two element <start_index, end_index> with a timestamp as its index.
-            - It indicates the `start_index`(included) and `end_index`(excluded) of the data for `timestamp`
+            - It indicates the `start_index` (included) and `end_index` (excluded) of the data for `timestamp`
 
         - meta data: cache/d41366901e25de3ec47297f12e2ba11d.meta
 

diff --git a/qlib/data/data.py b/qlib/data/data.py
@@ -220,7 +220,8 @@ def instruments(market: Union[List, str] = "all", filter_pipe: Union[List, None]
         ----------
         dict: if isinstance(market, str)
             dict of stockpool config.
-            {`market`=>base market name, `filter_pipe`=>list of filters}
+
+            {`market` => base market name, `filter_pipe` => list of filters}
 
             example :
 
@@ -432,9 +433,12 @@ def expression(self, instrument, field, start_time=None, end_time=None, freq="da
             data of a certain expression
 
             The data has two types of format
+
             1) expression with datetime index
+
             2) expression with integer index
-            - because the datetime is not as good as
+
+                - because the datetime is not as good as
         """
         raise NotImplementedError("Subclass of ExpressionProvider must implement `Expression` method")
 
@@ -890,6 +894,7 @@ def __init__(self, align_time: bool = True):
             Will we align the time to calendar
             the frequency is flexible in some dataset and can't be aligned.
             For the data with fixed frequency with a shared calendar, the align data to the calendar will provides following benefits
+
             - Align queries to the same parameters, so the cache can be shared.
         """
         super().__init__()
@@ -1167,11 +1172,12 @@ def features(
         inst_processors=[],
     ):
         """
-        Parameters:
-        -----------
+        Parameters
+        ----------
         disk_cache : int
             whether to skip(0)/use(1)/replace(2) disk_cache
 
+
         This function will try to use cache method which has a keyword `disk_cache`,
         and will use provider method if a type error is raised because the DatasetD instance
         is a provider class.
@@ -1221,10 +1227,12 @@ class ClientProvider(BaseProvider):
     """Client Provider
 
     Requesting data from server as a client. Can propose requests:
+
         - Calendar : Directly respond a list of calendars
         - Instruments (without filter): Directly respond a list/dict of instruments
         - Instruments (with filters):  Respond a list/dict of instruments
         - Features : Respond a cache uri
+
     The general workflow is described as follows:
     When the user use client provider to propose a request, the client provider will connect the server and send the request. The client will start to wait for the response. The response will be made instantly indicating whether the cache is available. The waiting procedure will terminate only when the client get the response saying `feature_available` is true.
     `BUG` : Everytime we make request for certain data we need to connect to the server, wait for the response and disconnect from it. We can't make a sequence of requests within one connection. You can refer to https://python-socketio.readthedocs.io/en/latest/client.html for documentation of python-socketIO client.

diff --git a/qlib/data/dataset/handler.py b/qlib/data/dataset/handler.py
@@ -35,7 +35,7 @@ class DataHandler(Serializable):
     Example of the data:
     The multi-index of the columns is optional.
 
-    .. code-block:: python
+    .. code-block:: text
 
                                 feature                                                            label
                                 $close     $volume  Ref($close, 1)  Mean($close, 3)  $high-$low  LABEL0
@@ -671,6 +671,7 @@ def get_cols(self, col_set=DataHandler.CS_ALL, data_key: str = DK_I) -> list:
     def cast(cls, handler: "DataHandlerLP") -> "DataHandlerLP":
         """
         Motivation
+
         - A user creates a datahandler in his customized package. Then he wants to share the processed handler to
           other users without introduce the package dependency and complicated data processing logic.
         - This class make it possible by casting the class to DataHandlerLP and only keep the processed data

diff --git a/qlib/data/dataset/loader.py b/qlib/data/dataset/loader.py
@@ -27,7 +27,7 @@ def load(self, instruments, start_time=None, end_time=None) -> pd.DataFrame:
 
         Example of the data (The multi-index of the columns is optional.):
 
-            .. code-block:: python
+            .. code-block:: text
 
                                         feature                                                             label
                                         $close     $volume     Ref($close, 1)  Mean($close, 3)  $high-$low  LABEL0

diff --git a/qlib/data/filter.py b/qlib/data/filter.py
@@ -272,8 +272,8 @@ class NameDFilter(SeriesDFilter):
     def __init__(self, name_rule_re, fstart_time=None, fend_time=None):
         """Init function for name filter class
 
-        params:
-        ------
+        Parameters
+        ----------
         name_rule_re: str
             regular expression for the name rule.
         """
@@ -325,8 +325,8 @@ class ExpressionDFilter(SeriesDFilter):
     def __init__(self, rule_expression, fstart_time=None, fend_time=None, keep=False):
         """Init function for expression filter class
 
-        params:
-        ------
+        Parameters
+        ----------
         fstart_time: str
             filter the feature starting from this time.
         fend_time: str

diff --git a/qlib/data/ops.py b/qlib/data/ops.py
@@ -1530,6 +1530,7 @@ def __init__(self, feature, freq, func):
         """
         Resampling the data to target frequency.
         The resample function of pandas is used.
+
         - the timestamp will be at the start of the time span after resample.
 
         Parameters
@@ -1632,10 +1633,14 @@ def register(self, ops_list: List[Union[Type[ExpressionOps], dict]]):
         ops_list : List[Union[Type[ExpressionOps], dict]]
             - if type(ops_list) is List[Type[ExpressionOps]], each element of ops_list represents the operator class, which should be the subclass of `ExpressionOps`.
             - if type(ops_list) is List[dict], each element of ops_list represents the config of operator, which has the following format:
-                {
-                    "class": class_name,
-                    "module_path": path,
-                }
+
+                .. code-block:: text
+
+                    {
+                        "class": class_name,
+                        "module_path": path,
+                    }
+
                 Note: `class` should be the class name of operator, `module_path` should be a python module or path of file.
         """
         for _operator in ops_list:
-Original file line number
+Diff line change
@@ Expand Up / @@ -4,3 +4,4 @@ numpy @@
     scipy
     scikit-learn
     pandas
+    tianshou