Merge pull request #306 from pyimgui/fix/doc

Fix compilation of documentation with Sphinx and ReadTheDocs

.gitignore

@@ -38,6 +38,9 @@ var/
 *.egg
 completion.svg
 
+# Documentation
+doc/source/_build/
+
 # Visual Studio stuff
 .vs/
 

.readthedocs.yaml

@@ -0,0 +1,34 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Git submodules
+submodules:
+  include: all
+  recursive: true
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.7"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: html
+  configuration: doc/source/conf.py
+  fail_on_warning: true
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - method: pip
+     path: .
+   - requirements: doc/requirements-docs.txt

doc/requirements-docs.txt

@@ -1,9 +1,10 @@
 Cython>=0.24,<0.30
-Sphinx==1.4.8
+Sphinx==1.8.6
 docutils<0.13.1
 PyOpenGL
 glfw
 pypandoc==1.4
 git-lfs
 mock
+Pillow
 -e.

doc/source/conf.py

@@ -32,37 +32,44 @@
 # because of that. Am I right?
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 if on_rtd:
-    from convert_readme import convert_md
-    convert_md()
-
-    render_examples = False
-
-    # hack for lacking git-lfs support on rtd
-    import git_lfs
-    try:
-        from urllib.error import HTTPError
-    except ImportError:
-        from urllib2 import HTTPError
-
-    _fetch_urls = git_lfs.fetch_urls
-
-    def _patched_fetch_urls(lfs_url, oid_list):
-        """Hack git_lfs library that sometimes makes too big requests"""
-        objects = []
-
-        try:
-            objects.extend(_fetch_urls(lfs_url, oid_list))
-        except HTTPError as err:
-            if err.code != 413:
-                raise
-            logger.error("LFS: request entity too large, splitting in half")
-            objects.extend(_patched_fetch_urls(lfs_url, oid_list[:len(oid_list) // 2]))
-            objects.extend(_patched_fetch_urls(lfs_url, oid_list[len(oid_list) // 2:]))
-
-        return objects
-
-    git_lfs.fetch_urls = _patched_fetch_urls
-    git_lfs.fetch(PROJECT_ROOT_DIR)
+    #from convert_readme import convert_md
+    #convert_md()
+    #
+    #render_examples = False
+    #
+    ## hack for lacking git-lfs support on rtd
+    #import git_lfs
+    #try:
+    #    from urllib.error import HTTPError
+    #except ImportError:
+    #    from urllib2 import HTTPError
+    #
+    #_fetch_urls = git_lfs.fetch_urls
+    #
+    #def _patched_fetch_urls(lfs_url, oid_list):
+    #    """Hack git_lfs library that sometimes makes too big requests"""
+    #    objects = []
+    #
+    #    try:
+    #        objects.extend(_fetch_urls(lfs_url, oid_list))
+    #    except HTTPError as err:
+    #        if err.code != 413:
+    #            raise
+    #        logger.error("LFS: request entity too large, splitting in half")
+    #        objects.extend(_patched_fetch_urls(lfs_url, oid_list[:len(oid_list) // 2]))
+    #        objects.extend(_patched_fetch_urls(lfs_url, oid_list[len(oid_list) // 2:]))
+    #
+    #    return objects
+    #
+    #git_lfs.fetch_urls = _patched_fetch_urls
+    #git_lfs.fetch(PROJECT_ROOT_DIR)
+
+    if not os.path.exists('./git-lfs'):
+        os.system('wget https://github.com/git-lfs/git-lfs/releases/download/v2.7.1/git-lfs-linux-amd64-v2.7.1.tar.gz')
+        os.system('tar xvfz git-lfs-linux-amd64-v2.7.1.tar.gz')
+        os.system('./git-lfs install')  # make lfs available in current repository
+        os.system('./git-lfs fetch')  # download content from remote
+        os.system('./git-lfs checkout')  # make local files to have the real content on them
 
 else:
     render_examples = True

doc/source/gen_example.py

@@ -58,7 +58,7 @@ def find_fonts(source):
 
     font_path = os.path.join(
         os.path.dirname(__file__),
-        '..', '..', 'imgui-cpp', 'misc', 'fonts', font_name
+        '../../imgui-cpp/misc/fonts', font_name
     )
     return source.replace(font_name, font_path)
 

doc/source/guide/tabbar-flag.rst → doc/source/guide/tabbar-flags.rst

@@ -8,6 +8,7 @@ Tab Bar functions accept various flags to manage their behaviour.
 List of all available tab bar flags (click to see documentation):
 
 .. _tabbar-flag-options:
+
 * :py:data:`imgui.TAB_BAR_NONE`
 * :py:data:`imgui.TAB_BAR_REORDERABLE`
 * :py:data:`imgui.TAB_BAR_AUTO_SELECT_NEW_TABS`
@@ -23,6 +24,7 @@ List of all available tab bar flags (click to see documentation):
 List of all available tab item flags (click to see documentation):
 
 .. _tabitem-flag-options:
+
 * :py:data:`imgui.TAB_ITEM_NONE`
 * :py:data:`imgui.TAB_ITEM_UNSAVED_DOCUMENT`
 * :py:data:`imgui.TAB_ITEM_SET_SELECTED`

doc/source/index.rst

@@ -1,6 +1,4 @@
 
-.. include:: readme.rst
-
 
 Contents
 ========

doc/source/reference/imgui.core.rst

@@ -17,7 +17,7 @@ imgui.core module
     :undoc-members:
 
 
-.. autoclass:: _StaticGlyphRanges
+.. autoclass:: imgui.core._StaticGlyphRanges
     :members:
     :undoc-members:
 

doc/source/reference/imgui.integrations.rst

@@ -5,17 +5,17 @@ imgui.integrations subpackage
     :undoc-members:
     :members:
 
-imgui.integrations.cocos2d module
----------------------------------
+imgui.integrations.glfw module
+------------------------------
 
-.. automodule:: imgui.integrations.cocos2d
+.. automodule:: imgui.integrations.glfw
     :undoc-members:
     :members:
 
-imgui.integrations.glfw module
-------------------------------
+imgui.integrations.cocos2d module
+---------------------------------
 
-.. automodule:: imgui.integrations.glfw
+.. automodule:: imgui.integrations.cocos2d
     :undoc-members:
     :members:
 

doc/source/reference/imgui.internal.rst

@@ -1,6 +1,6 @@
 imgui.internal module
-=================
+=====================
 
 .. automodule:: imgui.internal
-    :members:
     :undoc-members:
+    :members:

doc/source/reference/modules.rst

@@ -12,3 +12,4 @@ API reference
    imgui.core
    imgui.extra
    imgui.integrations
+   imgui.internal