Move tutorials to top level (#550)

* Minor fix

* Added nbsphinx-link

* Added relative paths

* added another relative path

* Moved tutorials and recipes

* updated references

* fixed Github action

* remove broken tests

* removed deprecated syntax

* formatting

* try recipes again

* remove recipes again

* Update HOW_TO_CONTRIBUTE.md

.github/workflows/test.yml

@@ -30,10 +30,55 @@ jobs:
         python -m pip install .
         python -m pip list
 
-    - name: Prepare tutorial notebooks
+    - name: Prepare case studies notebooks
       run: |
         # go into tutorial location
-        cd docs/source/api/tutorials/ 
+        cd tutorials/case_studies
+        # convert each notebook into a python file
+        jupyter nbconvert --to script *.ipynb
+        # rename the files so they are found by pytest: add 'test' at the beginning
+        rename 's/(.*)\.py/test $1.py/' *
+        # rename the files so they are found by pytest: change spaces to underscores
+        rename 's/ /_/g' test*
+        # modify each file by adding one level of indentation to each line
+        sed -i 's/^/    /' test*.py
+        # modify each file by adding 'def test_func():' at the top
+        sed -i '1s;^;def test_func():\n;' test*.py
+    
+    - name: Prepare focus notebooks
+      run: |
+        # go into tutorial location
+        cd tutorials/focus
+        # convert each notebook into a python file
+        jupyter nbconvert --to script *.ipynb
+        # rename the files so they are found by pytest: add 'test' at the beginning
+        rename 's/(.*)\.py/test $1.py/' *
+        # rename the files so they are found by pytest: change spaces to underscores
+        rename 's/ /_/g' test*
+        # modify each file by adding one level of indentation to each line
+        sed -i 's/^/    /' test*.py
+        # modify each file by adding 'def test_func():' at the top
+        sed -i '1s;^;def test_func():\n;' test*.py
+    
+    - name: Prepare getting started notebooks
+      run: |
+        # go into tutorial location
+        cd tutorials/getting_started
+        # convert each notebook into a python file
+        jupyter nbconvert --to script *.ipynb
+        # rename the files so they are found by pytest: add 'test' at the beginning
+        rename 's/(.*)\.py/test $1.py/' *
+        # rename the files so they are found by pytest: change spaces to underscores
+        rename 's/ /_/g' test*
+        # modify each file by adding one level of indentation to each line
+        sed -i 's/^/    /' test*.py
+        # modify each file by adding 'def test_func():' at the top
+        sed -i '1s;^;def test_func():\n;' test*.py
+
+    - name: Prepare in-depth notebooks
+      run: |
+        # go into tutorial location
+        cd tutorials/in_depth
         # convert each notebook into a python file
         jupyter nbconvert --to script *.ipynb
         # rename the files so they are found by pytest: add 'test' at the beginning
@@ -48,7 +93,18 @@ jobs:
     - name: Test tutorial notebooks
       run: |
         # run pytest ONLY on the tutorials
-        cd docs/source/api/tutorials/ 
+        cd tutorials
+
+        cd case_studies
+        pytest --color=yes
+
+        cd ../focus
+        pytest --color=yes
+
+        cd ../getting_started
+        pytest --color=yes
+
+        cd ../in_depth
         pytest --color=yes
 
   pytest:

HOW_TO_CONTRIBUTE.md

@@ -24,7 +24,7 @@ Please note we have a [code of conduct](/CODE_OF_CONDUCT.md), please follow it i
 ## New Version process
 1. Make sure that the Github Actions workflow runs without any errors.
 2. Using the `github-changelog` package (a dependency in the [release](requirements/release.txt) requirements file), run `changelog -m xgi-org xgi [last release tag]` to get the merged pull requests with their links. Paste this into the changelog file under a new heading and edit to make more legible. Associate a GitHub username with each pull request.
-3. Increase the version number in [setup.py](setup.py) and [conf.py](docs/source/conf.py) to the new version agreed upon by the core developers. The versioning scheme we use is [SemVer](http://semver.org/).
+3. Increase the version number in [\_\_init\_\_.py](xgi/__init__.py.py) and [conf.py](docs/source/conf.py) to the new version agreed upon by the core developers. The versioning scheme we use is [SemVer](http://semver.org/).
 4. Commit these changes.
 5. Create a new release on GitHub by selecting "Releases", then clicking "Draft a new release". Click "Choose a tag" and type "v" followed by the version number and then click "Create new tag". The release title will be this same string. Paste the contents of the CHANGELOG into the "Describe this release" field. Click "Publish release".
 6. Run `python setup.py sdist` from the main folder. This will create a zipped file to upload to PyPI and save it to the "dist" folder.

docs/source/api/convert.rst

@@ -9,7 +9,7 @@ convert package
 
    ~xgi.convert.bipartite_edges
    ~xgi.convert.bipartite_graph
-   ~xgi.encapsulation_dag
+   ~xgi.convert.encapsulation_dag
    ~xgi.convert.graph
    ~xgi.convert.higher_order_network
    ~xgi.convert.hyperedges

docs/source/api/recipes/recipes.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/recipes/recipes.ipynb"
+}

docs/source/api/tutorials.rst

@@ -6,7 +6,7 @@ Tutorials
    :maxdepth: 2
 
    tutorials/getting_started
-   tutorials/focus_tutorials
+   tutorials/focus
    tutorials/in_depth
    tutorials/case_studies
 

docs/source/api/tutorials/case_studies.rst

@@ -1,9 +1,9 @@
-##################
+############
 Case studies
-##################
+############
 
 .. toctree::
    :maxdepth: 1
 
-   case_study_zhang2022
-   simplicial_kuramoto_example
+   case_study_1
+   case_study_2

docs/source/api/tutorials/case_study_1.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/case_studies/case_study_zhang2022.ipynb"
+}

docs/source/api/tutorials/case_study_2.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/case_studies/simplicial_kuramoto_example.ipynb"
+}

docs/source/api/tutorials/focus.rst

@@ -0,0 +1,15 @@
+################
+ Focus tutorials
+################
+
+
+ .. toctree::
+    :maxdepth: 1
+
+    focus_1
+    focus_2
+    focus_3
+    focus_4
+    focus_5
+    focus_6
+    focus_7

docs/source/api/tutorials/focus_1.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/focus/Tutorial 1 - Basic Hypergraph Functionality.ipynb"
+}

docs/source/api/tutorials/focus_2.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/focus/Tutorial 2 - Read and Write.ipynb"
+}

docs/source/api/tutorials/focus_3.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/focus/Tutorial 3 - Basic simplicial complex usage.ipynb"
+}

docs/source/api/tutorials/focus_4.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/focus/Tutorial 4 - Generative_Models.ipynb"
+}

docs/source/api/tutorials/focus_5.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/focus/Tutorial 5 - Plotting.ipynb"
+}

docs/source/api/tutorials/focus_6.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/focus/Tutorial 6 - Statistics.ipynb"
+}

docs/source/api/tutorials/focus_7.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/focus/Tutorial 7 - Directed Hypergraphs.ipynb"
+}

docs/source/api/tutorials/getting_started.rst

@@ -1,10 +1,10 @@
-##################
+###############
 Getting started
-##################
+###############
 
 .. toctree::
    :maxdepth: 1
 
-   XGI in 1 minute
-   XGI in 5 minutes
-   XGI in 15 minutes
+   getting_started_1
+   getting_started_2
+   getting_started_3

docs/source/api/tutorials/getting_started_1.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/getting_started/XGI in 1 minute.ipynb"
+}

docs/source/api/tutorials/getting_started_2.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/getting_started/XGI in 5 minutes.ipynb"
+}

docs/source/api/tutorials/getting_started_3.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/getting_started/XGI in 15 minutes.ipynb"
+}

docs/source/api/tutorials/in_depth.rst

@@ -5,7 +5,7 @@ In Depth tutorials
 .. toctree::
    :maxdepth: 1
 
-   In Depth 1 - Drawing nodes
-   In Depth 2 - Drawing hyperedges
-   In Depth 3 - Drawing DiHypergraphs
-   In Depth 4 - Drawing multilayer-style
+   in_depth_1
+   in_depth_2
+   in_depth_3
+   in_depth_4

docs/source/api/tutorials/in_depth_1.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/in_depth/In Depth 1 - Drawing nodes.ipynb"
+}

docs/source/api/tutorials/in_depth_2.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/in_depth/In Depth 2 - Drawing hyperedges.ipynb"
+}

docs/source/api/tutorials/in_depth_3.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/in_depth/In Depth 3 - Drawing DiHypergraphs.ipynb"
+}

docs/source/api/tutorials/in_depth_4.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../../tutorials/in_depth/In Depth 4 - Drawing multilayer-style.ipynb"
+}

docs/source/conf.py

@@ -83,6 +83,7 @@
     "sphinx_copybutton",
     "sphinx_design",
     "nbsphinx",
+    "nbsphinx_link",
 ]
 
 # Automatically generate stub pages when using the .. autosummary directive

requirements/documentation.txt

@@ -6,4 +6,5 @@ pillow>=8.2
 matplotlib>=3.3
 sphinx-design
 ipykernel
-nbsphinx
+nbsphinx
+nbsphinx-link

setup.py

@@ -1,16 +1,32 @@
+import codecs
+import os.path
 import sys
 
 import setuptools
 from setuptools import setup
 
-__version__ = "0.8.6"
+name = "xgi"
+
+
+def read(rel_path):
+    here = os.path.abspath(os.path.dirname(__file__))
+    with codecs.open(os.path.join(here, rel_path), "r") as fp:
+        return fp.read()
+
+
+def get_version(rel_path):
+    for line in read(rel_path).splitlines():
+        if line.startswith("__version__"):
+            delim = '"' if '"' in line else "'"
+            return line.split(delim)[1]
+    else:
+        raise RuntimeError("Unable to find version string.")
+
 
 if sys.version_info < (3, 8):
     sys.exit("XGI requires Python 3.8 or later.")
 
-name = "xgi"
-
-version = __version__
+version = get_version("xgi/__init__.py")
 
 authors = "XGI Developers"
 

xgi/__init__.py

@@ -1,5 +1,3 @@
-import pkg_resources
-
 from . import (
     utils,
     core,
@@ -24,4 +22,4 @@
 from .stats import *
 
 
-__version__ = pkg_resources.require("xgi")[0].version
+__version__ = "0.8.6"

xgi/convert/encapsulation_dag.py

@@ -31,6 +31,7 @@ def to_encapsulation_dag(H, subset_types="all"):
                 encapsulate hyperedegs of size 3, which will be included if
                 using this setting (whereas relationships with subsets of size 2
                 would not be included).
+
     Returns
     -------
     LG : networkx.DiGraph
@@ -124,6 +125,7 @@ def _get_candidates(subset_types, H, he):
         The hypergraph
     he : Set
         The hyperedge
+
     Returns
     -------
     candidates : Set
@@ -153,6 +155,7 @@ def _check_candidate(subset_types, he, cand):
         The hyperedge
     cand : Set
         The candidate
+
     Returns
     -------
     is_candidate : bool