diff --git a/docs/conf.py b/docs/conf.py index 4c48120..176045a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,6 +14,9 @@ import sys sys.path.insert(0, os.path.abspath('../')) +import recommonmark +from recommonmark.transform import AutoStructify + # -- Project information ----------------------------------------------------- @@ -21,6 +24,8 @@ 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) + + + diff --git a/docs/dev_docs/HowToTutorial.md b/docs/dev_docs/HowToTutorial.md index cb9fd86..7c5922e 100644 --- a/docs/dev_docs/HowToTutorial.md +++ b/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,12 +270,21 @@ 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 @@ -246,9 +292,34 @@ 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. + +``` + +``` + + + + ### Datasets +Datasets should be located serperately, unless the size is small. Please [ask](https://github.com/SCIInstitute/UncertainSCI/discussions) if you have any questions. + diff --git a/docs/dev_docs/contribute.md b/docs/dev_docs/contribute.md new file mode 100644 index 0000000..3650735 --- /dev/null +++ b/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. + + diff --git a/docs/index.rst b/docs/index.rst index 527519b..1757d93 100644 --- a/docs/index.rst +++ b/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 ================== diff --git a/docs/references.bib b/docs/references.bib index 8080252..7a6253c 100644 --- a/docs/references.bib +++ b/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}, +} + diff --git a/docs/requirements.txt b/docs/requirements.txt index 47975a5..ef97ded 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -8,4 +8,3 @@ sphinx-notfound-page sphinx_rtd_theme sphinxcontrib-bibtex sphinx-markdown-tables - diff --git a/docs/tutorials/template.md b/docs/tutorials/template.md index 3e573af..722163f 100644 --- a/docs/tutorials/template.md +++ b/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: