Merge pull request #76 from SCIInstitute/pandoc_examples

citation  examples

Author: jessdtate

docs/conf.py

@@ -14,13 +14,18 @@
 import sys
 sys.path.insert(0, os.path.abspath('../'))
 
+import recommonmark
+from recommonmark.transform import AutoStructify
+
 
 # -- Project information -----------------------------------------------------
 
 project = 'UncertainSCI'
 copyright = '2020, The Scientific Computing and Imaging Institute at the University of Utah'
 author = 'Jake Bergquist, Dana Brooks, Zexin Liu, Rob MacLeod, Akil Narayan, Sumientra Rampersad, Lindsay Rupp, Jess Tate, Dan White'
 
+github_doc_root = 'https://github.com/SCIInstitute/UncertainSCI/tree/master/docs'
+
 # The full version, including alpha/beta/rc tags
 release = '0.01'
 
@@ -41,6 +46,7 @@
 # Path for bibtex files
 bibtex_bibfiles = ['references.bib']
 
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -98,3 +104,17 @@
 html_theme_options = {
     'logo_only': True
 }
+
+
+def setup(app):
+    app.add_config_value('recommonmark_config', {
+        #'url_resolver': lambda url: github_doc_root + url,
+        'auto_toc_tree_section': 'Contents',
+        'enable_math': False,
+        'enable_inline_math': False,
+        'enable_eval_rst': True,
+    }, True)
+    app.add_transform(AutoStructify)
+
+
+

docs/dev_docs/HowToTutorial.md

@@ -192,13 +192,50 @@ inline equations use the `\\(\mathbf{p}\\)` sytanx: \\(\mathbf{p}\\)
 
 ### Citations
 
-Sphinx has a built in citation manager for bibtex: [sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/). Works well for RST, but we are still working on it for markdown.  Another option may be [Myst](https://myst-parser.readthedocs.io/en/latest/)
+Since we are using Sphinx to build the documentation, we can use its citation manager, sphinxcontrib-bibtex.  We will provide some exmples here, but for more information, refer to the [sphinxcontrib-bibtex documentation](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/index.html).  
 
-TODO.
+Citations to include in the UncertainSCI docs can be included in the `UncertainSCI/docs/references.bib` file.  For the keys, please use the convention: Initials of the contributor, colon, first three letters of the author (with apropriate capitalization), and the year.  For example `JDT:Bur2020`.  For multiple citations from the same author in the same year, lowercase letters can be appended to the key: `JDT:Bur2020a`.  
 
+After the reference has been added to `UncertainSCI/docs/references.bib`, the final step is to include the command in the appropriate place.  
+
+The sphinxcontrib-bibtex is built to run with rst in Sphinx. However, it can be used in markdown using the [AutoStructify](https://recommonmark.readthedocs.io/en/latest/auto_structify.html) package.  This will require using using an `eval_rst` block as follows:
+
+````
+```eval_rst
+The whole paragraph will need to be in the eval_rst block :cite:p:`JDT:Bur2020`. For multiple references: :cite:p:`JDT:Bur2020,gupta1983`
+```
+````
+
+```eval_rst
+The whole paragraph will need to be in the eval_rst block :cite:p:`JDT:Bur2020`. For multiple references: :cite:p:`JDT:Bur2020,gupta1983`
+```
+
+add a bibliography section
+````
+```eval_rst
+.. bibliography::
+```
+````
+
+#### Bibliography
+```eval_rst
+.. bibliography::
+```
 
 ### Snippets
 
+Basic markdown ``some snippet``
+
+```
+def function():
+    return True
+```
+
+```python
+def function():
+    return True
+```
+
 ### Links
 Including links in Markdown is simple, just use `<>` or `[]()`.  For example, an internal link for section [Adding Content](#adding-content) is :
 ```
@@ -233,22 +270,56 @@ Tables can be used with normal markdown syntax with the [sphinx-markdown-tables]
 | Paragraph   | Text        |
 
 
+```eval_rst
++------------+------------+-----------+ 
+| Header 1   | Header 2   | Header 3  | 
++============+============+===========+ 
+| body row 1 | column 2   | column 3  | 
++------------+------------+-----------+ 
+| body row 2 | Cells may span columns.| 
++------------+------------+-----------+ 
+```
 
-### Referencing Sphynx
 
-TODO
+### Referencing Sphinx
 
-To link the UncertainSCI API generated using Sphynx, Use this syntax: [`[text](../api_docs/pce.html#polynomial-chaos-expansions)`](../api_docs/pce.html#polynomial-chaos-expansions).  
+
+To link the UncertainSCI API generated using Sphinx, Use this syntax: [`[text](../api_docs/pce.html#polynomial-chaos-expansions)`](../api_docs/pce.html#polynomial-chaos-expansions).  
 
 ## Content Guide
 
 TODO
 
 ## Supplemental Materials
 
-TODO
+Some things to consider including with the tutorial.  
 
 ### Example Scripts
+
+Example scripts should be located in the  `UncertainSCI/demos/` directory.  Consider using one of the existing demos as a template and try to follow the coding standards outlined in the [contribution guide](contribute.html).  
+
 ### Movies
+
+Movies should be stored in a serperate place.  We host most of ours on youtube or vimeo.  
+
+#### Youtube
+
+Get the imbed link from the youtube video.  This can be found by pressing the share button. 
+
+#### Vimeo
+
+Get the imbed link from the vimeo video.  This can be found by pressing the share button.  There are more options if for some users who own the video.  More info [here.](https://vimeo.zendesk.com/hc/en-us/articles/224969968-Embedding-videos-overview)
+
+With the embed link, just include the html into the markdown file.  
+
+```
+<iframe title="vimeo-player" src="https://player.vimeo.com/video/279319572" width="640" height="360" frameborder="0" allowfullscreen></iframe>
+```
+
+<iframe title="vimeo-player" src="https://player.vimeo.com/video/279319572" width="640" height="360" frameborder="0" allowfullscreen></iframe>
+
+
 ### Datasets
 
+Datasets should be located serperately, unless the size is small.  Please [ask](https://github.com/SCIInstitute/UncertainSCI/discussions) if you have any questions. 
+

docs/dev_docs/contribute.md

@@ -0,0 +1,9 @@
+# Contribution Guide
+
+Thank you for you cobributions to UncertainSCI!  
+
+If you'd like to make a tutorial, please follow the instructions in the [Tutorial Tutorial](HowToTutorial.html).  
+
+We will be filling in more directions about how to to contribute.  Try to do the best that you can.  
+
+

docs/index.rst

@@ -16,6 +16,9 @@ About UncertainSCI
 UncertainSCI is a Python-based toolkit that harnesses modern techniques to estimate model and parametric uncertainty, with a particular emphasis on needs for biomedical simulations and applications. This toolkit enables non-intrusive integration of these techniques with well-established biomedical simulation software.
 
 
+Currently implemented in UncertainSCI is Polynomial Chaos Expansion (PCE) with a number of input distributions.  For more information about these techniques, see: :cite:p:`JDT:Bur2020,narayan_computation_2018,guo_weighted_2018,cohen_optimal_2017`
+
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
@@ -36,6 +39,12 @@ Acknowledgements
 
 This project was supported by grants from the National Institute of Biomedical Imaging and Bioengineering (U24EB029012) from the National Institutes of Health.
 
+
+Bibliography
+================
+.. bibliography::
+
+
 Indices and Tables
 ==================
 

docs/references.bib

@@ -6,3 +6,58 @@ @techreport{gupta1983
 	author = {Gupta, S.K. and Harper, W.V.},
 	year = {1983},
 }
+
+@article{JDT:Bur2020,
+author = {Burk, Kyle M. and Narayan, Akil and Orr, Joseph A.},
+title = {Efficient sampling for polynomial chaos-based uncertainty quantification and sensitivity analysis using weighted approximate Fekete points},
+journal = {International Journal for Numerical Methods in Biomedical Engineering},
+volume = {36},
+number = {11},
+pages = {e3395},
+keywords = {approximate Fekete points, cardiovascular modeling, oxyhemoglobin dissociation, polynomial chaos expansion, sensitivity analysis, uncertainty quantification},
+doi = {https://doi.org/10.1002/cnm.3395},
+url = {https://onlinelibrary.wiley.com/doi/abs/10.1002/cnm.3395},
+year = {2020}
+}
+
+@article{narayan_computation_2018,
+	title = {Computation of induced orthogonal polynomial distributions},
+	volume = {50},
+	url = {https://epub.oeaw.ac.at?arp=0x003a184e},
+	doi = {10.1553/etna_vol50s71},
+	journal = {Electronic Transactions on Numerical Analysis},
+	author = {Narayan, Akil},
+	year = {2018},
+	note = {arXiv:1704.08465 [math]},
+	pages = {71--97},
+}
+
+
+@article{guo_weighted_2018,
+	title = {Weighted {Approximate} {Fekete} {Points}: {Sampling} for {Least}-{Squares} {Polynomial} {Approximation}},
+	volume = {40},
+	issn = {1064-8275},
+	shorttitle = {Weighted {Approximate} {Fekete} {Points}},
+	url = {http://epubs.siam.org/doi/abs/10.1137/17M1140960},
+	doi = {10.1137/17M1140960},
+	number = {1},
+	journal = {SIAM Journal on Scientific Computing},
+	author = {Guo, L. and Narayan, A. and Yan, L. and Zhou, T.},
+	year = {2018},
+	note = {arXiv:1708.01296 [math.NA]},
+	pages = {A366--A387},
+}
+
+
+@article{cohen_optimal_2017,
+	title = {Optimal weighted least-squares methods},
+	volume = {3},
+	issn = {2426-8399},
+	doi = {10.5802/smai-jcm.24},
+	journal = {SMAI Journal of Computational Mathematics},
+	author = {Cohen, Albert and Migliorati, Giovanni},
+	year = {2017},
+	note = {arxiv:1608.00512 [math.NA]},
+	pages = {181--203},
+}
+

docs/requirements.txt

@@ -8,4 +8,3 @@ sphinx-notfound-page
 sphinx_rtd_theme
 sphinxcontrib-bibtex
 sphinx-markdown-tables
-

docs/tutorials/template.md

@@ -55,9 +55,19 @@ inline equations use the `\\(\mathbf{p}\\)` sytanx: \\(\mathbf{p}\\)
 
 ### Citations
 
-Sphinx has a built in citation manager for bibtex: [sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/). Works well for RST, but we are still working on it for markdown.  Another option may be [Myst](https://myst-parser.readthedocs.io/en/latest/)
+Sphinx has a built in citation manager for bibtex: [sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/). Works well for RST, but we are still working on it for markdown.  The sphinxcontrib-bibtex is built to run with rst in Sphinx. However, it can be used in markdown using the [AutoStructify](https://recommonmark.readthedocs.io/en/latest/auto_structify.html) package.
 
-TODO.
+```eval_rst
+The whole paragraph will need to be in the eval_rst block :cite:p:`JDT:Bur2020`. For multiple references: :cite:p:`JDT:Bur2020,gupta1983`
+```
+
+
+add a bibliography section
+````
+```eval_rst
+.. bibliography::
+```
+````
 
 ### Snippets
 Inline snippets `like this`.  Muliple lines: