[ci][docs] replace file extensions in docs during Sphinx build (#3738)

* replace file extensions in docs during Sphinx build

* Update .travis.yml

* Update .travis.yml

* Update conf.py

* fix lint

* fix lint

.ci/test.sh

@@ -29,8 +29,6 @@ if [[ $TASK == "check-docs" ]]; then
     rstcheck --report warning --ignore-directives=autoclass,autofunction,doxygenfile `find . -type f -name "*.rst"` || exit -1
     # build docs and check them for broken links
     make html || exit -1
-    find ./_build/html/ -type f -name '*.html' -exec \
-    sed -i'.bak' -e 's;\(\.\/[^.]*\.\)rst\([^[:space:]]*\);\1html\2;g' {} \;  # emulate js function
     linkchecker --config=.linkcheckerrc ./_build/html/*.html || exit -1
     # check the consistency of parameters' descriptions and other stuff
     cp $BUILD_DIRECTORY/docs/Parameters.rst $BUILD_DIRECTORY/docs/Parameters-backup.rst

docs/_static/js/script.js

 $(function() {
-    /* Replace '.rst' with '.html' in all internal links like './[Something].rst[#anchor]' */
-    $('a[href^="./"][href*=".rst"]').attr('href', (i, val) => { return val.replace('.rst', '.html'); });
-
     /* Use wider container for the page content */
     $('.wy-nav-content').each(function() { this.style.setProperty('max-width', 'none', 'important'); });
 

docs/conf.py

@@ -23,7 +23,10 @@ import sys
 import sphinx
 
 from distutils.dir_util import copy_tree
+from docutils.nodes import reference
 from docutils.parsers.rst import Directive
+from docutils.transforms import Transform
+from re import compile
 from sphinx.errors import VersionRequirementError
 from subprocess import PIPE, Popen
 from unittest.mock import Mock
@@ -32,6 +35,8 @@ CURR_PATH = os.path.abspath(os.path.dirname(__file__))
 LIB_PATH = os.path.join(CURR_PATH, os.path.pardir, 'python-package')
 sys.path.insert(0, LIB_PATH)
 
+INTERNAL_REF_REGEX = compile(r"(?P<url>\.\/.+)(?P<extension>\.rst)(?P<anchor>$|#)")
+
 # -- mock out modules
 MOCK_MODULES = ['numpy', 'scipy', 'scipy.sparse',
                 'sklearn', 'matplotlib', 'pandas', 'graphviz']
@@ -39,6 +44,19 @@ for mod_name in MOCK_MODULES:
     sys.modules[mod_name] = Mock()
 
 
+class InternalRefTransform(Transform):
+    """Replaces '.rst' with '.html' in all internal links like './[Something].rst[#anchor]'."""
+
+    default_priority = 210
+    """Numerical priority of this transform, 0 through 999."""
+
+    def apply(self, **kwargs):
+        """Apply the transform to the document tree."""
+        for section in self.document.traverse(reference):
+            if section.get("refuri") is not None:
+                section["refuri"] = INTERNAL_REF_REGEX.sub(r"\g<url>.html\g<anchor>", section["refuri"])
+
+
 class IgnoredDirective(Directive):
     """Stub for unknown directives."""
 
@@ -305,5 +323,6 @@ def setup(app):
         app.connect("build-finished",
                     lambda app, exception: copy_tree(os.path.join(CURR_PATH, os.path.pardir, "lightgbm_r", "docs"),
                                                      os.path.join(app.outdir, "R"), verbose=0))
+    app.add_transform(InternalRefTransform)
     add_js_file = getattr(app, 'add_js_file', False) or app.add_javascript
     add_js_file("js/script.js")