Added nblink option to control placement of notebook links (#92)

* Added nblink argument to generate_rst function

* Added --nblink option to commandline

* Added tests for new nblink option

* Fixed type of nblink type in the parser

Co-Authored-By: jlstevens <jlrstevens@gmail.com>

* Adding list of choices and improving test

nbsite/__main__.py

@@ -32,7 +32,8 @@ def main(args=None):
     generaterst_parser.add_argument('--branch',type=str,help='where to init doc',default='master')
     generaterst_parser.add_argument('--offset',type=int,help='where to init doc',default=0)
     generaterst_parser.add_argument('--overwrite',type=int,help='where to init doc',default=False)
-    generaterst_parser.add_argument('--skip',type=str,help=' notebooks to skip running; comma separated case insensitive re to match',default='')
+    generaterst_parser.add_argument('--nblink',type=str,help='where to place notebook links',choices=['bottom', 'top', 'none'], default='bottom')
+    generaterst_parser.add_argument('--skip',type=str,help='notebooks to skip running; comma separated case insensitive re to match',default='')
     _set_defaults(generaterst_parser,generate_rst)
 
     build_parser = subparsers.add_parser("build", help=inspect.getdoc(build))

nbsite/cmd.py

@@ -70,6 +70,7 @@ def generate_rst(
         branch='master',
         offset=0,
         overwrite=False,
+        nblink='bottom',
         skip=''):
     """Auto-generates notebook-including rsts from notebooks in examples.
 
@@ -162,15 +163,25 @@ def generate_rst(
             rst_file.write('*'*len(title)+'\n')
             rst_file.write(title+'\n')
             rst_file.write('*'*len(title)+'\n\n')
+
+            if nblink == 'top':
+                add_nblink(rst_file, host,org,repo, branch, examples, fromhere)
+
             rst_file.write(".. notebook:: %s %s" % (project_name,os.path.relpath(paths['examples'],start=dirname(rst))+'/'+fromhere+"\n"))
             rst_file.write("    :offset: %s\n" % offset)
 
             if pretitle=='index':
                 rst_file.write("%s\n"%_toctree(dirname(filename),paths['examples']))
-            elif all([host,org,repo,branch]):
-                rst_file.write('\n\n-------\n\n')
-                rst_file.write('`Right click to download this notebook from ' + host + '.'
-                               ' <%s/%s/%s/%s/%s/%s>`_\n' % (hosts[host],org,repo,branch,examples,fromhere))
+            if nblink == 'bottom':
+                add_nblink(rst_file, host,org,repo, branch, examples, fromhere)
+
+
+def add_nblink(rst_file, host,org,repo,branch,examples, fromhere):
+    if all([host,org,repo,branch]):
+        info = (hosts[host],org,repo,branch,examples,fromhere)
+        rst_file.write('\n\n-------\n\n')
+        rst_file.write('`Right click to download this notebook from ' + host + '.'
+                       ' <%s/%s/%s/%s/%s/%s>`_\n' % info)
 
 def _should_skip(skip, filename):
     if skip == '':

nbsite/tests/test_cmd.py

@@ -180,6 +180,64 @@ def test_generate_rst_with_skip_glob_matching_both_notebooks_undercase(tmp_proje
     assert not (project / "doc" / "Example_Notebook_0.rst").is_file()
     assert not (project / "doc" / "Example_Notebook_1.rst").is_file()
 
+def test_generate_rst_with_nblink_as_none(tmp_project):
+
+    expected = ['******************',
+                'Example Notebook 1',
+                '******************',
+                '', '.. notebook:: test_project ../examples/Example_Notebook_1.ipynb',
+                '    :offset: 0']
+    project = tmp_project
+    generate_rst("test_project", project_root=str(project), nblink='none',
+                 host='GitHub', org='pyviz', repo='nbsite', branch='master')
+    rstpath = (project / "doc" / "Example_Notebook_1.rst")
+    assert rstpath.is_file()
+    with open(rstpath, 'r') as f:
+        contents = f.read().splitlines()
+        assert  contents[5:] == expected
+
+def test_generate_rst_with_nblink_top(tmp_project):
+
+    expected = ['`Right click to download this notebook from GitHub. <https://raw.githubusercontent.com/pyviz/nbsite/master/examples/Example_Notebook_1.ipynb>`_',
+                '.. notebook:: test_project ../examples/Example_Notebook_1.ipynb',
+                '    :offset: 0']
+
+    project = tmp_project
+    generate_rst("test_project", project_root=str(project), nblink='top',
+                 host='GitHub', org='pyviz', repo='nbsite', branch='master')
+    rstpath = (project / "doc" / "Example_Notebook_1.rst")
+    assert rstpath.is_file()
+    with open(rstpath, 'r') as f:
+        contents = f.read().splitlines()
+        assert  contents[-3:] == expected
+
+def test_generate_rst_with_nblink_bottom(tmp_project):
+
+    expected = ['-------', '',
+                '`Right click to download this notebook from GitHub. <https://raw.githubusercontent.com/pyviz/nbsite/master/examples/Example_Notebook_1.ipynb>`_']
+
+    project = tmp_project
+    generate_rst("test_project", project_root=str(project), nblink='bottom',
+                 host='GitHub', org='pyviz', repo='nbsite', branch='master')
+    rstpath = (project / "doc" / "Example_Notebook_1.rst")
+    assert rstpath.is_file()
+    with open(rstpath, 'r') as f:
+        contents = f.read().splitlines()
+        assert  contents[-3:] == expected
+
+def test_generate_rst_with_no_nblink_set_defaults_to_bottom(tmp_project):
+    expected = ['-------', '',
+                '`Right click to download this notebook from GitHub. <https://raw.githubusercontent.com/pyviz/nbsite/master/examples/Example_Notebook_1.ipynb>`_']
+
+    project = tmp_project
+    generate_rst("test_project", project_root=str(project),
+                 host='GitHub', org='pyviz', repo='nbsite', branch='master')
+    rstpath = (project / "doc" / "Example_Notebook_1.rst")
+    assert rstpath.is_file()
+    with open(rstpath, 'r') as f:
+        contents = f.read().splitlines()
+        assert  contents[-3:] == expected
+
 #### Don't need to do much testing of build it depends on sphinx
 @pytest.mark.slow
 def test_build(tmp_project_with_docs_skeleton):