Readthedocs

.gitignore

@@ -18,6 +18,7 @@ vendor/install/
 .DS_Store
 
 doc/source/gallery.rst
+doc/linkcheck
 doc/api/
 doc/dash/
 doc/html/

.readthedocs.yaml

@@ -0,0 +1,49 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+submodules:
+  include:
+    - vendor/source/igraph
+  recursive: true
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  apt_packages:
+    - cmake
+    - flex
+    - bison
+    - libxml2-dev
+    - zlib1g-dev
+
+  tools:
+    python: "3.9"
+    # You can also specify other tool versions:
+    # nodejs: "16"
+    # rust: "1.55"
+    # golang: "1.17"
+
+  jobs:
+    pre_build:
+      - bash ./scripts/rtd_prebuild.sh
+      # One website complains about legacy SSL renegotiation (?), skip for now
+      #- python -m sphinx -b linkcheck doc/source/ _build/linkcheck
+
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: doc/source/conf.py
+
+# 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:
+   - requirements: doc/source/requirements.txt
+

doc/source/analysis.rst

@@ -6,7 +6,7 @@
 Graph analysis
 ==============
 
-|igraph| enables analysis of graphs/networks from simple operations such as adding and removing nodes to complex theoretical constructs such as community detection. Read the `API documentation`_ for details on each function and class.
+|igraph| enables analysis of graphs/networks from simple operations such as adding and removing nodes to complex theoretical constructs such as community detection. Read the :doc:`api/index` for details on each function and class.
 
 The context for the following examples will be to import |igraph| (commonly as `ig`), have the :class:`Graph` class and to have one or more graphs available::
 
@@ -51,7 +51,7 @@ You can index and slice vertices and edges like indexing and slicing a list::
     >>> g.vs[0, 2, 4]
     >>> g.es[3]
 
-.. note:: The `vs` and `es` attributes are special sequences with their own useful methods. See `API documentation`_ for a full list.
+.. note:: The `vs` and `es` attributes are special sequences with their own useful methods. See the :doc:`api/index` for a full list.
 
 If you prefer a vanilla edge list, you can use :meth:`Graph.get_edge_list`.
 
@@ -442,5 +442,3 @@ Flow and cuts are closely related, therefore you might find the following functi
 - :meth:`Graph.all_st_mincuts`
 - :meth:`Graph.edge_connectivity` or :meth:`Graph.edge_disjoint_paths` or :meth:`Graph.adhesion`
 - :meth:`Graph.vertex_connectivity` or :meth:`Graph.cohesion`
-
-.. _API documentation: https://igraph.org/python/api/latest/

doc/source/conf.py

@@ -15,58 +15,52 @@
 
 import sys
 import os
-import os.path as op
+import importlib
+from pathlib import Path
 import sphinxbootstrap4theme
 
 
+# Check if we are inside readthedocs, the conf is quite different there
+is_inside_rtd = os.getenv("READTHEDOCS", "") == "True"
+rtd_version = os.getenv("READTHEDOCS_VERSION", "")
+
+
 # Utility functions
 # NOTE: these could be improved, esp by importing igraph, but that
-# currently generates a conflict with pydoctor
+# currently generates a conflict with pydoctor. It is funny because pydoctor's
+# docs indeed import itself... perhaps there's a decent way to solve this.
 def get_root_dir():
     '''Get project root folder'''
-    root_folder = op.abspath('../..')
-    return root_folder
+    return str(Path('.').absolute().parent.parent)
 
 
 def get_igraphdir():
     '''Get igraph folder'''
-    vmaj, vmin = sys.version_info[:2]
-    root_folder = get_root_dir()
-    ig_folder = op.join(
-        root_folder,
-        '.venv',
-        'lib',
-        f'python{vmaj}.{vmin}',
-        'site-packages',
-        'igraph',
-    )
-    return ig_folder
+    return Path(importlib.util.find_spec('igraph').origin).parent
 
 
 def get_igraph_version():
     '''Get igraph version'''
-    version_file = op.join(
-        get_igraphdir(),
-        'version.py',
-    )
+    if is_inside_rtd:
+        return rtd_version
+
+    version_file = get_igraphdir() / 'version.py'
     with open(version_file, 'rt') as f:
         version_info = (f.readline()
                          .rstrip('\n')
                          .split('=')[1]
                          .strip()[1:-1]
                          .split(', '))
-        version = '.'.join(version_info)
-        
+    version = '.'.join(version_info)
+
     return version
 
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.append(os.path.abspath('.'))
-
 # -- General configuration -----------------------------------------------------
 
+_igraph_dir = str(get_igraphdir())
+_igraph_version = get_igraph_version()
+
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
@@ -78,32 +72,14 @@ def get_igraph_version():
     'sphinx.ext.mathjax',
     'sphinx.ext.intersphinx',
     'gallery_generator',
-    'pydoctor.sphinx_ext.build_apidocs',
-    'postprocess_api',
     #'sphinx_panels',
+    'pydoctor.sphinx_ext.build_apidocs',
 ]
 
-# Using --no-sidebar option to skip the sidebar whole together not to generate noise in the HTML.
-# Because the pydoctor output is integrated in a smaller div with a custom CSS it's not optimal to include the sidebar.
-pydoctor_args = [
-    '--project-name="igraph"',
-    '--project-version=' + get_igraph_version(),
-    '--project-url=https://igraph.org/python',
-    '--introspect-c-modules',
-    '--no-sidebar',
-    '--docformat=epytext',
-    #'--intersphinx='+get_root_dir()+'/doc/tutorial/objects.inv',
-    '--html-output=' + op.join(get_root_dir(), 'doc', 'html', 'api'),
-    #'--html-viewsource-base=https://github.com/igraph/python-igraph/tree/default',
-    '--project-base-dir=' + get_igraphdir(),
-    get_igraphdir(),
-]
-
-# API docs relative to the rest of the docs
-# NOTE: there is a bug in pydoctor that requires this to be a subfolder
-# of the main docs. Although we patch pydoctor to work anyway, links might
-# be broken if that constraint is not satisfied
-pydoctor_url_path = 'api/'
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.append(os.path.abspath('.'))
 
 # The suffix of source filenames.
 source_suffix = '.rst'
@@ -123,7 +99,7 @@ def get_igraph_version():
 # built documents.
 #
 # The short X.Y version.
-version = get_igraph_version()
+version = _igraph_version
 # The full version, including alpha/beta/rc tags.
 release = version
 
@@ -164,26 +140,50 @@ def get_igraph_version():
 
 # -- Options for HTML output ---------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-html_theme = 'sphinxbootstrap4theme'
-#html_theme = 'alabaster'
+# The theme to use for HTML and HTML Help pages. RTD overloads this with their
+# standard theme if the variable 'html_theme' is not set
+if not is_inside_rtd:
+    html_theme = 'sphinxbootstrap4theme'
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = [
-        '_templates',
-]
+    # Add any paths that contain templates here, relative to this directory.
+    templates_path = [
+            '_templates',
+    ]
 
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-html_theme_options = {
-        "navbar_style": "full",
-        "navbar_color_class": "dark",
-}
+    # Theme options are theme-specific and customize the look and feel of a theme
+    # further.  For a list of options available for each theme, see the
+    # documentation.
+    html_theme_options = {
+            "navbar_style": "full",
+            "navbar_color_class": "dark",
+    }
+
+    # Add any paths that contain custom themes here, relative to this directory.
+    html_theme_path = [sphinxbootstrap4theme.get_path()]
+
+    # Add any paths that contain custom static files (such as style sheets) here,
+    # relative to this directory. They are copied after the builtin static files,
+    # so a file named "default.css" will overwrite the builtin "default.css".
+    html_static_path = ['_static']
+
+    # If false, no module index is generated.
+    html_domain_indices = False
+
+    # If false, no index is generated.
+    html_use_index = False
+
+    # If true, the index is split into individual pages for each letter.
+    #html_split_index = False
+
+    # If true, links to the reST sources are added to the pages.
+    html_show_sourcelink = False
 
-# Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = [sphinxbootstrap4theme.get_path()]
+else:
+
+    # Inspired by pydoctor's RTD page itself
+    # https://github.com/twisted/pydoctor/blob/master/docs/source/conf.py
+    html_theme = "sphinx_rtd_theme"
+    html_static_path = []
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -201,11 +201,6 @@ def get_igraph_version():
 # pixels large.
 #html_favicon = None
 
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'
@@ -221,18 +216,6 @@ def get_igraph_version():
 # template names.
 #html_additional_pages = {}
 
-# If false, no module index is generated.
-html_domain_indices = False
-
-# If false, no index is generated.
-html_use_index = False
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-html_show_sourcelink = False
-
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 #html_show_sphinx = True
 
@@ -251,6 +234,49 @@ def get_igraph_version():
 htmlhelp_basename = 'igraphdoc'
 
 
+# -- Options for pydoctor ------------------------------------------------------
+
+def get_pydoctor_html_outputdir(pydoctor_url_path):
+    '''Get HTML output dir for pydoctor'''
+    # NOTE: obviously this is a little tricky, but it does work for both
+    # the sphinx-build script and the python -m sphinx module calls. It works
+    # locally, on github pages, and on RTD.
+    return str(Path(sys.argv[-1]) / pydoctor_url_path.strip('/'))
+
+
+# API docs relative to the rest of the docs, needed for pydoctor to play nicely
+# with intersphinx (https://pypi.org/project/pydoctor/#pydoctor-21-2-0)
+# NOTE: As of 2022 AD, pydoctor requires this to be a subfolder of the docs.
+pydoctor_url_path = 'api/'
+
+pydoctor_args = [
+    '--project-name="igraph"',
+    '--project-version=' + version,
+    '--project-url=https://igraph.readthedocs.io',
+    '--introspect-c-modules',
+    '--docformat=epytext',
+    #'--intersphinx='+get_root_dir()+'/doc/tutorial/objects.inv',
+    '--html-output=' + get_pydoctor_html_outputdir(pydoctor_url_path),
+    #'--html-viewsource-base=https://github.com/igraph/python-igraph/tree/default',
+    '--project-base-dir=' + _igraph_dir,
+    ]
+
+# Using --no-sidebar option to skip the sidebar because the pydoctor output is
+# integrated in a smaller div with a custom CSS.
+if not is_inside_rtd:
+    pydoctor_args.extend([
+        '--no-sidebar',
+        ])
+else:
+    pydoctor_args.extend([
+        '--theme=readthedocs',
+        ])
+pydoctor_args.append(_igraph_dir)
+
+# RTD needs no postprocessing for pydoctor, while Jekyll does
+if not is_inside_rtd:
+    extensions.append('postprocess_api')
+
 # -- Options for LaTeX output --------------------------------------------------
 
 # The paper size ('letter' or 'a4').

doc/source/generation.rst

@@ -7,7 +7,7 @@
 Graph generation
 ================
 
-The first step of most |igraph| applications is to generate a graph. This section will explain a number of ways to do that. Read the `API documentation`_ for details on each function and class.
+The first step of most |igraph| applications is to generate a graph. This section will explain a number of ways to do that. Read the :doc:`api/index` for details on each function and class.
 
 The :class:`Graph` class is the main object used to generate graphs::
 
@@ -55,7 +55,7 @@ a representation that uses Python builtin data structures:
  - :meth:`Graph.to_list_dict`
  - :meth:`Graph.to_dict_dict`
 
-See the `API documentation`_ of each function for details and examples.
+See the :doc:`api/index` of each function for details and examples.
 
 From matrices
 +++++++++++++
@@ -208,5 +208,3 @@ Finally, there are some ways of generating graphs that are not covered by the pr
  - graphs from LCF notation :meth:`Graph.LCF`
  - small graphs of any "isomorphism class" :meth:`Graph.Isoclass`
  - graphs with a specified degree sequence :meth:`Graph.Realize_Degree_Sequence`
-
-.. _API documentation: https://igraph.org/python/api/latest/