[REVIEW] DOC Adding Nx transition doc and preping for more (#1217)

* Added new Medium entry * updated to match cuML * copied to match cuML * updated list of MG algorithms * converted to Markdown * updated reference to new markdown file * removed rst file * should really be a HTML file (next release) * copy pdf files over * updates * removed ref to cuml * changelog * addressing review issues * migrated to RST Co-authored-by: BradReesWork <[email protected]>
rapidsai · Oct 14, 2020 · 715e374 · 715e374
1 parent d9457af
commit 715e374
Show file tree

Hide file tree

Showing 15 changed files with 534 additions and 38 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -33,7 +33,7 @@
 - PR #1165 updated remaining algorithms to be NetworkX compatible
 - PR #1176 Update ci/local/README.md
 - PR #1184 BLD getting latest tags
-
+- PR #1217 NetworkX Transition doc
 
 ## Bug Fixes
 - PR #1131 Show style checker errors with set +e

diff --git a/README.md b/README.md
@@ -41,7 +41,7 @@ for i in range(len(df_page)):
 |              | Edge Betweenness Centrality            | Single-GPU   |                     |
 | Community    |                                        |              |                     |
 |              | Leiden                                 | Single-GPU   |                     |
-|              | Louvain                                | Single-GPU   |                     |
+|              | Louvain                                | Multiple-GPU |                     |
 |              | Ensemble Clustering for Graphs         | Single-GPU   |                     |
 |              | Spectral-Clustering - Balanced Cut     | Single-GPU   |                     |
 |              | Spectral-Clustering - Modularity       | Single-GPU   |                     |
@@ -57,16 +57,16 @@ for i in range(len(df_page)):
 | Layout       |                                        |              |                     |
 |              | Force Atlas 2                          | Single-GPU   |                     |
 | Link Analysis|                                        |              |                     |
-|              | Pagerank                               | Multiple-GPU | limited to 2 billion vertices |
-|              | Personal Pagerank                      | Multiple-GPU | limited to 2 billion vertices |
+|              | Pagerank                               | Multiple-GPU |                     |
+|              | Personal Pagerank                      | Single-GPU  |                     |
 |              | HITS                      				| Single-GPU   | leverages Gunrock   |
 | Link Prediction |                                     |              |                     |
 |              | Jaccard Similarity                     | Single-GPU   |                     |
 |              | Weighted Jaccard Similarity            | Single-GPU   |                     |
 |              | Overlap Similarity                     | Single-GPU   |                     |
 | Traversal    |                                        |              |                     |
-|              | Breadth First Search (BFS)             | Multiple-GPU | limited to 2 billion vertices |
-|              | Single Source Shortest Path (SSSP)     | Single-GPU   |                     |
+|              | Breadth First Search (BFS)             | Multiple-GPU |                     |
+|              | Single Source Shortest Path (SSSP)     | Multiple-GPU |                     |
 | Structure    |                                        |              |                     |
 |              | Renumbering                            | Single-GPU   | Also for multiple columns  |
 |              | Symmetrize                             | Single-GPU   |                     |
@@ -81,9 +81,7 @@ for i in range(len(df_page)):
 ## cuGraph Notice
 The current version of cuGraph has some limitations:
 
-- Vertex IDs need to be 32-bit integers (that restriction is going away in 0.16)
 - Vertex IDs are expected to be contiguous integers starting from 0.
---  If the starting index is not zero, cuGraph will add disconnected vertices to fill in the missing range.  (Auto-) Renumbering fixes this issue
 
 cuGraph provides the renumber function to mitigate this problem, which is by default automatically called when data is addted to a graph.  Input vertex IDs for the renumber function can be any type, can be non-contiguous, can be multiple columns, and can start from an arbitrary number. The renumber function maps the provided input vertex IDs to 32-bit contiguous integers starting from 0. cuGraph still requires the renumbered vertex IDs to be representable in 32-bit integers. These limitations are being addressed and will be fixed soon.
 
@@ -96,7 +94,7 @@ The amount of memory required is dependent on the graph structure and the analyt
 
 |       Size        | Recommended GPU Memory |
 |-------------------|------------------------|
-| 500 million edges |  32 GB                  |
+| 500 million edges |  32 GB                 |
 | 250 million edges |  16 GB                 |
 
 The use of managed memory for oversubscription can also be used to exceed the above memory limitations.  See the recent blog on _Tackling Large Graphs with RAPIDS cuGraph and CUDA Unified Memory on GPUs_:  https://medium.com/rapids-ai/tackling-large-graphs-with-rapids-cugraph-and-unified-virtual-memory-b5b69a065d4

diff --git a/docs/Makefile b/docs/Makefile
@@ -7,6 +7,7 @@ SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = cuGraph
 SOURCEDIR     = source
 BUILDDIR      = build
+IMGDIR        = images
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -18,3 +19,4 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	cp -r $(SOURCEDIR)/$(IMGDIR) $(BUILDDIR)/html
diff --git a/docs/source/_static/copybutton.css b/docs/source/_static/copybutton.css
@@ -0,0 +1,42 @@
+/* This contains code with copyright by the scikit-learn project, subject to
+the license in /thirdparty/LICENSES/LICENSE.scikit_learn */
+
+/* copybutton */
+/* Adds "Show/Hide Output" button to Examples */
+
+.copybutton {
+  cursor: pointer;
+  position: absolute;
+  top: 0px;
+  right: 0px;
+  border: 1px solid rgb(221, 221, 221);
+  color: rgb(221, 221, 221);
+  font-family: monospace;
+  padding-left: 0.2rem;
+  padding-right: 0.2rem;
+}
+
+div.highlight:hover span.copybutton::after {
+  background: #3F556B;
+  border-radius: 0.25rem;
+  color: white;
+  content: attr(title);
+  padding: 0.25rem;
+  position: absolute;
+  z-index: 98;
+  width: 100px;
+  font-size: 0.7rem;
+  top: 0;
+  right: 0;
+}
+
+/* copy buttonn */
+div.highlight:hover span.copybutton {
+  background-color: #3F556B;
+  color: white;
+}
+
+div.highlight:hover span.copybutton:hover {
+  background-color: #20252B;
+}
+
diff --git a/docs/source/_static/example_mod.js b/docs/source/_static/example_mod.js
@@ -0,0 +1,61 @@
+// This contains code with copyright by the scikit-learn project, subject to
+// the license in /thirdparty/LICENSES/LICENSE.scikit_learn
+
+$(document).ready(function () {
+   /* Add a [>>>] button on the top-right corner of code samples to hide
+    * the >>> and ... prompts and the output and thus make the code
+    * copyable. */
+   var div = $('.highlight-python .highlight,' +
+      '.highlight-python3 .highlight,' +
+      '.highlight-pycon .highlight,' +
+      '.highlight-default .highlight')
+   var pre = div.find('pre');
+
+   // get the styles from the current theme
+   pre.parent().parent().css('position', 'relative');
+   var hide_text = 'Hide prompts and outputs';
+   var show_text = 'Show prompts and outputs';
+
+   // create and add the button to all the code blocks that contain >>>
+   div.each(function (index) {
+      var jthis = $(this);
+      if (jthis.find('.gp').length > 0) {
+         var button = $('<span class="copybutton">&gt;&gt;&gt;</span>');
+         button.attr('title', hide_text);
+         button.data('hidden', 'false');
+         jthis.prepend(button);
+      }
+      // tracebacks (.gt) contain bare text elements that need to be
+      // wrapped in a span to work with .nextUntil() (see later)
+      jthis.find('pre:has(.gt)').contents().filter(function () {
+         return ((this.nodeType == 3) && (this.data.trim().length > 0));
+      }).wrap('<span>');
+   });
+
+   // define the behavior of the button when it's clicked
+   $('.copybutton').click(function (e) {
+      e.preventDefault();
+      var button = $(this);
+      if (button.data('hidden') === 'false') {
+         // hide the code output
+         button.parent().find('.go, .gp, .gt').hide();
+         button.next('pre')
+            .find('.gt')
+            .nextUntil('.gp, .go')
+            .css('visibility', 'hidden');
+         button.css('text-decoration', 'line-through');
+         button.attr('title', show_text);
+         button.data('hidden', 'true');
+      } else {
+         // show the code output
+         button.parent().find('.go, .gp, .gt').show();
+         button.next('pre')
+            .find('.gt')
+            .nextUntil('.gp, .go')
+            .css('visibility', 'visible');
+         button.css('text-decoration', 'none');
+         button.attr('title', hide_text);
+         button.data('hidden', 'false');
+      }
+   });
+});
diff --git a/docs/source/_static/references.css b/docs/source/_static/references.css
@@ -0,0 +1,23 @@
+
+/* Fix references to not look like parameters */
+dl.citation > dt.label {
+  display: unset !important;
+  float: left !important;
+  border: unset !important;
+  background: unset !important;
+  padding: unset !important;
+  margin: unset !important;
+  font-size: unset !important;
+  line-height: unset !important;
+  padding-right: 0.5rem !important;
+}
+
+/* Add opening bracket */
+dl.citation > dt.label > span::before {
+  content: "[";
+}
+
+/* Add closing bracket */
+dl.citation > dt.label > span::after {
+  content: "]";
+}
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
-# Copyright (c) 2018, NVIDIA CORPORATION.
+# Copyright (c) 2018-2020 NVIDIA CORPORATION.
 #
 # pygdf documentation build configuration file, created by
 # sphinx-quickstart on Wed May  3 10:59:22 2017.
@@ -21,8 +21,17 @@
 #
 import os
 import sys
+
+# 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.insert(0, os.path.abspath('sphinxext'))
+sys.path.insert(0, os.path.abspath('../../python'))
 sys.path.insert(0, os.path.abspath('../..'))
 
+from github_link import make_linkcode_resolve # noqa
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -33,14 +42,20 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.intersphinx',
+    'numpydoc',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
-    'numpydoc',
-    'IPython.sphinxext.ipython_console_highlighting',
-    'IPython.sphinxext.ipython_directive',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.linkcode',
+    "IPython.sphinxext.ipython_console_highlighting",
+    "IPython.sphinxext.ipython_directive",
+    "nbsphinx",
+    "recommonmark",
+    "sphinx_markdown_tables",
 ]
 
+
 ipython_mplbackend = 'str'
 
 # Add any paths that contain templates here, relative to this directory.
@@ -50,7 +65,7 @@
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
 
 # The master toctree document.
 master_doc = 'index'
@@ -151,7 +166,7 @@
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
     (master_doc, 'cugraph.tex', 'cugraph Documentation',
-     'Continuum Analytics', 'manual'),
+     'nvidia', 'manual'),
 ]
 
 
@@ -187,12 +202,13 @@
 
 
 def setup(app):
-    app.add_stylesheet('params.css')
+    app.add_css_file('copybutton.css')
+    app.add_css_file('params.css')
+    app.add_css_file('references.css')
 
-from recommonmark.parser import CommonMarkParser
-
-source_parsers = {
-    '.md': CommonMarkParser,
-}
 
-source_suffix = ['.rst', '.md']
+# The following is used by sphinx.ext.linkcode to provide links to github
+linkcode_resolve = make_linkcode_resolve(
+    'cugraph', 'https://github.com/rapidsai/'
+    'cugraph/blob/{revision}/python/'
+    '{package}/{path}#L{lineno}')
diff --git a/docs/source/cugraph_blogs.rst b/docs/source/cugraph_blogs.rst
@@ -22,6 +22,7 @@ BLOGS
 ------
   * `Status of RAPIDS cuGraph — Refactoring Code And Rethinking Graphs <https://medium.com/rapids-ai/status-of-rapids-cugraph-refactoring-code-and-rethinking-graphs-efe9956d5528>`_
   * `Tackling Large Graphs with RAPIDS cuGraph and CUDA Unified Memory on GPUs <https://medium.com/rapids-ai/tackling-large-graphs-with-rapids-cugraph-and-unified-virtual-memory-b5b69a065d4>`_
+  * `RAPIDS cuGraph adds NetworkX and DiGraph Compatibility <https://t.co/6DEhyarVGa>`_
 
 
 Media

diff --git a/docs/source/cugraph_intro.md b/docs/source/cugraph_intro.md
@@ -0,0 +1,22 @@
+
+# cuGraph Introduction
+
+
+## Terminology
+
+cuGraph is a collection of GPU accelerated graph algorithms and graph utility
+functions. The application of graph analysis covers a lot of areas.
+For Example:
+* [Network Science](https://en.wikipedia.org/wiki/Network_science)
+* [Complex Network](https://en.wikipedia.org/wiki/Complex_network)
+* [Graph Theory](https://en.wikipedia.org/wiki/Graph_theory)
+* [Social Network Analysis](https://en.wikipedia.org/wiki/Social_network_analysis)
+
+cuGraph does not favor one field over another.  Our developers span the
+breadth of fields with the focus being to produce the best graph library
+possible.  However, each field has its own argot (jargon) for describing the
+graph (or network).  In our documentation, we try to be consistent.  In Python
+documentation we will mostly use the terms __Node__ and __Edge__ to better
+match NetworkX preferred term use, as well as other Python-based tools.  At
+the CUDA/C layer, we favor the mathematical terms of __Vertex__ and __Edge__.  
+
diff --git a/docs/source/cugraph_intro.rst b/docs/source/cugraph_intro.rst
diff --git a/docs/source/images/Nx_Cg_1.png b/docs/source/images/Nx_Cg_1.png
diff --git a/docs/source/images/Nx_Cg_2.png b/docs/source/images/Nx_Cg_2.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -5,12 +5,12 @@ Welcome to cugraph's documentation!
    :maxdepth: 4
    :caption: Contents:
 
+   cugraph_intro.md
    api.rst
    dask-cugraph.rst
-   cugraph_intro.rst
    cugraph_blogs.rst
    cugraph_ref.rst
-
+   nx_transition.rst
 
 Indices and tables
 ==================
-Original file line number
+Diff line change
@@ Expand Up / @@ -22,6 +22,7 @@ BLOGS @@
     ------
       * `Status of RAPIDS cuGraph — Refactoring Code And Rethinking Graphs <https://medium.com/rapids-ai/status-of-rapids-cugraph-refactoring-code-and-rethinking-graphs-efe9956d5528>`_
       * `Tackling Large Graphs with RAPIDS cuGraph and CUDA Unified Memory on GPUs <https://medium.com/rapids-ai/tackling-large-graphs-with-rapids-cugraph-and-unified-virtual-memory-b5b69a065d4>`_
+      * `RAPIDS cuGraph adds NetworkX and DiGraph Compatibility <https://t.co/6DEhyarVGa>`_
     Media
@@ Expand Down @@