Add tutorial to docs

[teubert]

Update docs to send users to tutorial juypter notebook. I want to make it obvious, some way of making sure users get there first. Current thinking is as a large text link and badge on documentation home page (and readme), a badge on getting started, and a option in the side navigation menu, but I'll leave it up to whoever implements this to see what works the best.

I was thinking of using binder instead of embedding the notebook text. Something like this: https://mybinder.org/v2/gh/nasa/prog_models/dev?labpath=tutorial.ipynb. Note: binder can automatically generate badges. See: https://mybinder.org

---

Previous Text: Tools exist to add jupyter notebooks to sphinx doc (see https://blog.jupyter.org/integrating-output-in-documentation-with-jupyter-sphinx-ecf569ddab85, https://nbsphinx.readthedocs.io/en/0.8.7/).

I would like to setup sphinx to include the tutorial as it's own page.

[anonymousr007]

Hi @teubert, I'm Rishabh, undergraduate student in computer science in India. Can you elaborate little bit more? I would like to make a pull request for this issue 😄.

[teubert]

Hello @anonymousr007, Thanks for your interest in contributing.

This issue is intended to improve the documentation. I was considering trying to turn the tutorial into its own page in github.io (https://nasa.github.io/prog_models/). These pages are generated using sphinx-docs (https://www.sphinx-doc.org/en/master/) from the files int he folder sphinx-config/ and written into the docs folder.

To make it easier for users to get started, I was thinking about creating a page for the tutorial. Rather than duplicate the code, I wanted to generate a separate page for this.

However, I've recently decided against this approach in favor of linking to binder, something like this: https://mybinder.org/v2/gh/nasa/prog_models/dev?labpath=tutorial.ipynb.

I'll update the issue accordingly.

Out of curiosity: Are you doing any work in prognostics?

[teubert]

Follow-up: If you're interested in contributing please complete a Contributor License Agreement and send it to christopher.a.teubert@nasa.gov. You can find them here: https://github.com/nasa/prog_models/blob/master/forms/Individual%20CLA.pdf

[anonymousr007]

Follow-up: If you're interested in contributing please complete a Contributor License Agreement and send it to christopher.a.teubert@nasa.gov. You can find them here: https://github.com/nasa/prog_models/blob/master/forms/Individual%20CLA.pdf

Thanks for the information. Yes, I'm interested to contributing. So, we sign on CLA as digitally name ?

[anonymousr007]

Basically, we make a beginner friendly tutorial for prog_models same like this tutorial.ipynb using sphinx-docs in sphinx-config/ folder.

Thanks, if something missing here please let me know 👍🏻

I did no work in prognostics but work in

• Languages such as C, C++, Python and Javascript
• Machine Learning
• Deep Learning
• Quantum Computing
• Quantum Machine Learning
• Quantum Nature, Quantum Chemistry, Quantum Finance, Quantum Optimization modules

Recently, I merged two pull request in Cirq [ Google ] and one in Pennylane [ Xanadu ]. I've core knowledge of computer science of data structure, algorithms, operating systems and so on... Glad to work in prognostics, what is it and what's use of this and why we use this?

[teubert]

@anonymousr007, That's right, except we don't want to replicate tutorial.ipynb, instead we want to set it up so the user can see and ideally run the tutorial. MyBinder makes that easy (https://mybinder.org/v2/gh/nasa/prog_models/dev?labpath=tutorial.ipynb). So this issue is actually a pretty minor one since we're only adding the links now.

That's great that you've done some work in quantum computing. I'm familiar with Cirq and have used it in the past. Are you familiar with github.com/nasa/hybridq? That the new quantum circuit simulation software that is developed by my group's sister group at NASA Ames. With your experience in quantum computing that might interest you. Note that they've only just released and they're in alpha.

Glad to work in prognostics, what is it and what's use of this and why we use this?

Prognostics is the science of predicting how systems will degrade with time and eventually fail. It's used to schedule maintenance (see also: predictive maintenance), plan to extend useful life (prognostics-aware planning and scheduling), and take action to prevent failure (fault mitigation and hazard control). This software is a set of research tools for individuals and groups at NASA, universities, and companies doing research in prognostics and health management (PHM). This package (prog_models) is centered around the simulation of degrading systems, and it's sister package (prog_algs) has tools for using models to perform active prognostics.

[anonymousr007]

@anonymousr007, That's right, except we don't want to replicate tutorial.ipynb, instead we want to set it up so the user can see and ideally run the tutorial. MyBinder makes that easy (https://mybinder.org/v2/gh/nasa/prog_models/dev?labpath=tutorial.ipynb). So this issue is actually a pretty minor one since we're only adding the links now.

Okay, Here is the list of tasks, we do for this issue, I think this is the good way to understand the whole scenerio about the issue and easily handle the things in a simple manner 😄

• [x] Fork and Star this repository.
• [x] Completed the Contributor License Agreement (CLA) and send it to you.
• [x] Badge for .md file is working properly.
• [x] Add this Badge in README.md file
• [x] Also badge add on https://nasa.github.io/prog_models/ but where ?

I make a pull request for this issue after my CLA will approve. Thank you @teubert and please let me know something wrong or missing here.

[teubert]

This is right.

For updating in nasa.github.io/prog_models, the changes are made in the sphinx-config directory. Sphinx uses these configuration files to generate the documentation from the source code.

See https://nasa.github.io/prog_models/dev_guide.html#updating-documentation for how to update the documentation. But, do not include the updated documentation in the PR, just the updated config files. Generate the documentation on your own machine to check the changes.

Updating the todo list:

• [x] Add this Badge in README.md file
• [ ] add on https://nasa.github.io/prog_models/ by adding to the sphinx-config files
  • [ ] Add badge
  • [ ] Add link in side navigation (see sphinx docs)
  • [ ] Build according to directions and check the html files in docs (but do not check them in).

Does that make sense?

I also updated the destination to be the dev branch.

[anonymousr007]

This is right.

For updating in nasa.github.io/prog_models, the changes are made in the sphinx-config directory. Sphinx uses these configuration files to generate the documentation from the source code.

See https://nasa.github.io/prog_models/dev_guide.html#updating-documentation for how to update the documentation. But, do not include the updated documentation in the PR, just the updated config files. Generate the documentation on your own machine to check the changes.

Updating the todo list:

• [x] Add this Badge in README.md file

• [ ] add on https://nasa.github.io/prog_models/ by adding to the sphinx-config files

  • [ ] Add badge
  • [ ] Add link in side navigation (see sphinx docs)
  • [ ] Build according to directions and check the html files in docs (but do not check them in).

Does that make sense?

I also updated the destination to be the dev branch.

• Make a new file in sphinx-config/tutorial.rst
• tutorial add in this file https://github.com/nasa/prog_models/blob/master/sphinx_config/index.rst
• add badge in tutorial.rst or index.rst file ?

[teubert]

The badge should be in index.rst.

Re: the tutorial.rst file. I'm guessing there's a way to add the MyBinder link to the navigation bar without creating a tutorial.rst file. But that'll require some searching through sphinx documentation to figure out.

If that's not possible I'm ok with a .rst page the redirects to the my binder link

[anonymousr007]

This looks good I guess

[teubert]

Looks great!

[anonymousr007]

So, we push it :)

[teubert]

The only thing remaining is the link in the side navigation.

[anonymousr007]

LGTM 👍🏻

[teubert]

Perfect!

[anonymousr007]

Right Now, It's Perfect 😄 In index.rst, we add

Tutorial <https://mybinder.org/v2/gh/nasa/prog_models/dev?labpath=tutorial.ipynb>

this code automatically changes in most of the file and deployment too and it's working. I've a basic question, there is almost 46 files changes in my vs code, so push it all, Right ?

[teubert]

Great! I'm glad it worked!

Push all relevant changes in sphinx-config folder. If there's anything not relevant to this issue/PR, it'll have to be a separate PR.

[teubert]

Thank you @anonymousr007! I appreciate your help

If you're interested, I would like to make the same change to nasa/prog_algs as well (see https://github.com/nasa/prog_algs/issues/86)

[anonymousr007]

Thank you @anonymousr007! I appreciate your help

If you're interested, I would like to make the same change to nasa/prog_algs as well (see nasa/prog_algs#86)

Yeah, I'll do it and we are contributor in prog_models 🎉