Merge pull request #110 from ihuicatl/docs

Update documentation for Read the Docs

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# Contributing to Jupyter-ROS
+# Contributing
 
-First off, thank you for considering contributing to Jupyter-ROS. It's people like you that make Jupyter-ROS such a great tool.
+First off, thank you for considering contributing to Jupyter-ROS 🥳. It's people like you that make Jupyter-ROS such a great tool.
 
 
 Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.
@@ -11,25 +11,25 @@ Jupyter-ROS is an open source project and we love to receive contributions from
 - submit bug reports or feature requests
 - write code to incorporate into Jupyter-ROS itself
 
-# Ground Rules
+## Ground Rules
 
 We welcome all kinds of contribution and value them highly. We pledge to treat everyone's contribution fairly and with respect, and we are here to bring awesome pull requests over the finish line.
 
 Please note that we adhere to the [Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/) and by contributing to this project you also agree to follow the same guidelines.
 
 
-# Your First Contribution
+## Your First Contribution
 
 Working on your first Pull Request? Here are some resources to help you get started:
 - [First Timers Only](https://www.firsttimersonly.com/)
 - [Make a Pull Request](https://makeapullrequest.com/)
 - [How to Contribute to an Open Source Project on GitHub](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github)
 
-At this point, you're ready to make your changes! Feel free to ask for help; everyone is a beginner at first :smile_cat:
+At this point, you're ready to make your changes! Feel free to ask for help; everyone is a beginner at first 😸.
 
 If a maintainer asks you to "rebase" your PR, they're saying that a lot of code has changed and that you need to update your branch so that it's easier to merge.
 
-# Getting started
+## Getting Started
 
 1. Create your own fork of the code.
 2. Do the changes in your fork.
@@ -45,17 +45,17 @@ If a maintainer asks you to "rebase" your PR, they're saying that a lot of code
 7. If you are happy with your changes, create a pull request.
 
 
-# How to report a bug
+## How to Report a Bug
 
-## Security
+### Security
 
-If you find a security vulnerability, do NOT open an issue. Email [email protected] instead. In order to determine whether you are dealing with a security issue, ask yourself these two questions:
+If you find a security vulnerability, do NOT open an issue. Email [[email protected]](mailto:[email protected]) instead. In order to determine whether you are dealing with a security issue, ask yourself these two questions:
 - Can I access something that's not mine, or something I shouldn't have access to?
 - Can I disable something for other people?
 
 If the answer to either of those two questions are "yes", then you're probably dealing with a security issue. Note that even if you answer "no" to both questions, you may still be dealing with a security issue, so if you're unsure, just email us.
 
-## Other bugs
+### Other bugs
 
 When filing an issue, make sure to answer these five questions:
 
@@ -68,15 +68,15 @@ When filing an issue, make sure to answer these five questions:
 General questions should be handled through [Gitter](https://gitter.im/RoboStack/Lobby) instead of the issue tracker. The maintainers there will answer or ask you to file an issue if you've tripped over a bug.
 
 
-# How to suggest a feature or enhancement
+## How to Suggest a Feature or Enhancement
 
 If you find yourself wishing for a feature that doesn't exist in Jupyter-ROS, you are probably not alone. There are bound to be others out there with similar needs. Many of the features that Jupyter-ROS has today have been added because our users saw the need. Open an issue on our [issues list](https://github.com/RoboStack/jupyter-ros/issues) on GitHub which includes the following:
 
 1. A description of the feature you would like to see
 2. Why do you need it?
 3. How should it work?
 
-# Code review process
+## Code Review Process
 
 Any change to resources in this repository must be through pull requests. This applies to all changes to documentation, code, binary files, etc. No pull request can be merged without being reviewed.
 
@@ -85,9 +85,6 @@ The core team looks at Pull Requests on a regular basis and provides feedback af
 A pull request will be merged once all the feedback has been addressed and there are no objections by any of the committers.
 
 
-# Community
-
-You can chat with the core team on https://gitter.im/RoboStack/Lobby. We try to answer all questions within 48 hours.
-
-
+## Community
 
+You can chat with the core team on [gitter.im/RoboStack](https://gitter.im/RoboStack/Lobby). We try to answer all questions within 48 hours.

README.md

@@ -6,8 +6,8 @@ robotics community has not jumped on the band wagon yet!
 Most tools around ROS, the Robot Operating System, are
 built using Python and QT.
 
-However, using QT seperates the user away from the code.
-We've built an initial version of the ROS tools for jupyter
+However, using QT separates the user away from the code.
+We've built a set of ROS tools for jupyter
 notebook, trying to promote a rich, interactive experience
 for Robotics developers utilizing the power of the jupyter
 notebook.
@@ -19,10 +19,7 @@ notebook.
 With jupyter-ros, it's possible to easily create widgets for
 custom message types to send messages.
 
-In the future, we plan to bring simple and fast real-time
-plotting from ROS topics to this library.
-
-If you find this initial package useful, don't hesitate to
+If you find this package useful, don't hesitate to
 contribute!
 You can also always reach out to [email protected] or
 on twitter: https://twitter.com/wuoulf, or join us on [Gitter](https://gitter.im/RoboStack/Lobby)
@@ -60,9 +57,7 @@ To update the `defaults.js` javascript you need to run `python jupyros/ros3d.py`
 You might see a warning like "The rospy package is not found in your $PYTHONPATH.
 Subscribe and publish are not going to work. Do you need to activate your ROS environment?"
 
-This is harmless during installation, but if you see this warning in a notebook, you should
-check that your ROS environment is activated. You can also set the path from inside the notebook
-using
+This is harmless during installation, but if you see this warning in a notebook, you should check that your ROS environment is activated. You can also set the path from inside the notebook using
 
 ```
 import sys

docs/README.md

@@ -0,0 +1,32 @@
+# Building Jupyter-ROS Documentation
+
+1. Create a new environment with the following dependencies
+
+   - `sphinx`
+   - `myst-parser`
+   - `jinja2=3.0`
+   - `sphinx-rtd-theme`
+
+   ```sh
+   $ mamba create jupyros_docs sphinx myst-parser jinja2=3.0 -c conda-forge
+   $ mamba activate jupyros_docs
+   $ pip install sphinx-rtd-theme
+   ```
+
+1. [Optional] Install `jupyter-ros` in the environment. This is only necessary for the _References_ page to display correctly; otherwise, there will be a few warnings in the next step.
+
+1. Build the documents
+
+   ```sh
+   $ cd jupyter-ros/docs/
+   $ make html
+   ```
+
+1. Open the documentation locally
+
+   ```sh
+   $ cd build/html/
+   $ python -m http.server
+   ```
+
+1. From a web browser, navigate to `localhost:8000`

docs/source/conf.py

@@ -19,11 +19,11 @@
 # -- Project information -----------------------------------------------------
 
 project = 'jupyter-ros'
-copyright = '2020, Wolf Vollprecht'
+copyright = '2022, Wolf Vollprecht'
 author = 'Wolf Vollprecht'
 
 # The full version, including alpha/beta/rc tags
-release = '0.3.0'
+release = '0.6.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -34,6 +34,7 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
+    'myst_parser',
     # 'sphinx.ext.intersphinx',
     # 'sphinx.ext.autosummary',
     # 'sphinx.ext.viewcode',

docs/source/dev_contributing.md

@@ -0,0 +1,88 @@
+# Contributing
+
+First off, thank you for considering contributing to Jupyter-ROS 🥳. It's people like you that make Jupyter-ROS such a great tool.
+
+Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.
+
+Jupyter-ROS is an open source project and we love to receive contributions from our community — you! There are many ways to contribute. For example, you can
+
+- write a new tutorial or a blog post
+- improve the documentation or the existing examples
+- submit bug reports or feature requests
+- write code to incorporate into Jupyter-ROS itself
+
+## Ground Rules
+
+We welcome all kinds of contribution and value them highly. We pledge to treat everyone's contribution fairly and with respect, and we are here to bring awesome pull requests over the finish line.
+
+Please note that we adhere to the [Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/) and by contributing to this project you also agree to follow the same guidelines.
+
+## Your First Contribution
+
+Working on your first Pull Request? Here are some resources to help you get started:
+
+- [First Timers Only](https://www.firsttimersonly.com/)
+- [Make a Pull Request](https://makeapullrequest.com/)
+- [How to Contribute to an Open Source Project on GitHub](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github)
+
+At this point, you're ready to make your changes! Feel free to ask for help; everyone is a beginner at first 😸.
+
+If a maintainer asks you to "rebase" your PR, they're saying that a lot of code has changed and that you need to update your branch so that it's easier to merge.
+
+## Getting Started
+
+1. Create your own fork of the code.
+2. Do the changes in your fork.
+3. If your changes only involve spelling or grammar fixes, move to step 7.
+4. Test your changes in a clean environment and update installation instructions and dependencies as needed.
+5. When adding new features, make sure to update the documentation and provide an example under _notebooks/_.
+6. New notebooks
+   - Remove all output.
+   - Remove unnecessary cells.
+   - Include a descriptive title.
+   - Specify ROS version in the notebook name, "_ROS Turtlesim.ipynb_" vs "_ROS**2** Turtlesim.ipynb_"
+   - Any additional steps the user needs to take to run all the cells in the notebook should be clearly stated in markdown cells.
+7. If you are happy with your changes, create a pull request.
+
+## How to Report a Bug
+
+### Security
+
+If you find a security vulnerability, do NOT open an issue. Email [[email protected]](mailto:[email protected]) instead. In order to determine whether you are dealing with a security issue, ask yourself these two questions:
+
+- Can I access something that's not mine, or something I shouldn't have access to?
+- Can I disable something for other people?
+
+If the answer to either of those two questions are "yes", then you're probably dealing with a security issue. Note that even if you answer "no" to both questions, you may still be dealing with a security issue, so if you're unsure, just email us.
+
+### Other bugs
+
+When filing an issue, make sure to answer these five questions:
+
+1. What version of _jupyros_ are you using?
+2. What operating system and processor architecture are you using?
+3. What did you do?
+4. What did you expect to see?
+5. What did you see instead?
+
+General questions should be handled through [Gitter](https://gitter.im/RoboStack/Lobby) instead of the issue tracker. The maintainers there will answer or ask you to file an issue if you've tripped over a bug.
+
+## How to Suggest a Feature or Enhancement
+
+If you find yourself wishing for a feature that doesn't exist in Jupyter-ROS, you are probably not alone. There are bound to be others out there with similar needs. Many of the features that Jupyter-ROS has today have been added because our users saw the need. Open an issue on our [issues list](https://github.com/RoboStack/jupyter-ros/issues) on GitHub which includes the following:
+
+1. A description of the feature you would like to see
+2. Why do you need it?
+3. How should it work?
+
+## Code Review Process
+
+Any change to resources in this repository must be through pull requests. This applies to all changes to documentation, code, binary files, etc. No pull request can be merged without being reviewed.
+
+The core team looks at Pull Requests on a regular basis and provides feedback after each review. Once feedback has been given, we expect responses within three weeks. After the three weeks have elapsed, we may close the pull request if it isn't showing any activity.
+
+A pull request will be merged once all the feedback has been addressed and there are no objections by any of the committers.
+
+## Community
+
+You can chat with the core team on [gitter.im/RoboStack](https://gitter.im/RoboStack/Lobby). We try to answer all questions within 48 hours.

docs/source/dev_installation.rst

@@ -0,0 +1,89 @@
+.. _dev-install-label:
+
+Developer Installation
+======================
+
+
+Install Jupyter-ROS
+-------------------
+
+1. Clone repository
+
+   .. code-block:: sh
+
+     $ git clone [email protected]:RoboStack/jupyter-ros.git
+     $ cd jupyter-ros
+
+2. Create a conda environment for development with the following packages
+
+   * ``python = 3.9``
+   * ``jupyterlab``
+   * ``jupyter-packaging``
+   * ``nodejs <= 15``
+   * ``ros-noetic-desktop``
+
+   .. code-block:: sh
+
+      # You can use conda as well
+      $ mamba create -n jupyros_env python=3.9 jupyterlab jupyter-packaging nodejs=15 ros-noetic-desktop -c conda-forge -c robostack
+
+      $ mamba activate jupyros_end
+
+3. Install *jupyter-ros* in editable mode
+
+   .. code-block:: sh
+
+      # From the jupyter-ros root directory
+      $ pip install -e .
+
+4. Symlink the JupyterLab extension
+
+   .. code-block:: sh
+
+      $ jupyter labextension develop . --overwrite
+
+5. Verify installation with Python
+
+   .. code-block:: python
+
+      import jupyros
+      print(jupyros.__file__)
+      # Should return /home/user/jupyter-ros/jupyros/__init__.py
+
+
+
+Build Documentation
+-------------------
+
+1. Create a new conda environment with the following dependencies:
+
+   * ``sphinx``
+   * ``myst-parser``
+   * ``jinja2 <= 3.0``
+   * ``sphinx-rtd-theme``
+
+   .. code-block:: sh
+
+    # You can use conda as well
+    $ mamba create -n jupyros_docs sphinx myst-parser jinja2=3.0 -c conda-forge
+    $ mamba activate jupyros_docs
+    $ pip install sphinx-rtd-theme
+
+2. **[Optional]** Install ``jupyter-ros`` in the environment. This is only necessary for the *References* page to display correctly; otherwise, there will be a few warnings in the next step.
+
+3. Build the documents
+
+   .. code-block:: sh
+
+    $ cd jupyter-ros/docs/
+    $ make html
+
+
+4. Open the documentation locally
+
+   .. code-block:: sh
+
+    $ cd build/html/
+    $ python -m http.server
+
+5. From a web browser, navigate to ``localhost:8000``