Improve documentation (pykeen#106)

Author: cthoyt

README.md

@@ -83,7 +83,7 @@ result = pipeline(
 )
 ```
 
-The results are returned in an instance of the [RankBasedMetricResults](https://pykeen.readthedocs.io/en/latest/reference/evaluation/rank_based.html#pykeen.evaluation.RankBasedMetricResults)
+The results are returned in an instance of the [PipelineResult](https://pykeen.readthedocs.io/en/latest/reference/pipeline.html#pykeen.pipeline.PipelineResult)
 dataclass that has attributes for the trained model, the training loop, the evaluation, and more. See the tutorials on
 [understanding the evaluation](https://pykeen.readthedocs.io/en/latest/tutorial/understanding_evaluation.html)
 and [making novel link predictions](https://pykeen.readthedocs.io/en/latest/tutorial/making_predictions.html).

docs/source/index.rst

@@ -35,6 +35,7 @@ PyKEEN
    reference/negative_sampling
    reference/hpo
    reference/lookup
+   reference/sealant
 
 .. toctree::
    :caption: Appendix

docs/source/reference/sealant.rst

@@ -0,0 +1,4 @@
+Sealant
+=======
+.. automodule:: pykeen.triples.leakage
+    :members:

src/pykeen/templates/README.md

@@ -83,7 +83,7 @@ result = pipeline(
 )
 ```
 
-The results are returned in an instance of the [RankBasedMetricResults](https://pykeen.readthedocs.io/en/latest/reference/evaluation/rank_based.html#pykeen.evaluation.RankBasedMetricResults)
+The results are returned in an instance of the [PipelineResult](https://pykeen.readthedocs.io/en/latest/reference/pipeline.html#pykeen.pipeline.PipelineResult)
 dataclass that has attributes for the trained model, the training loop, the evaluation, and more. See the tutorials on
 [understanding the evaluation](https://pykeen.readthedocs.io/en/latest/tutorial/understanding_evaluation.html)
 and [making novel link predictions](https://pykeen.readthedocs.io/en/latest/tutorial/making_predictions.html).

src/pykeen/triples/leakage.py

@@ -1,6 +1,13 @@
 # -*- coding: utf-8 -*-
 
-"""Tools for removing the leakage from datasets."""
+"""Tools for removing the leakage from datasets.
+
+Leakage is when the inverse of a given training triple appears in either
+the testing or validation set. This scenario generally leads to inflated
+and misleading evaluation because predicting an inverse triple is usually
+very easy and not a sign of the generalizability of a model to predict
+novel triples.
+"""
 
 import itertools as itt
 import logging