Merge pull request #3 from dwave-examples/documentation

Documentation and Instructions

CONTRIBUTING.md

@@ -1,71 +1,112 @@
 # Contribution Guidelines
 
-Thank you for your interest in contributing to [dwave-examples](https://github.com/dwave-examples)! Before getting
-started, we encourage you to take a look at the following guidelines.
+Thank you for your interest in contributing to [dwave-examples](https://github.com/dwave-examples)!
+Before getting started, we encourage you to take a look at the following guidelines.
 
 ## What We're Looking For
 
-While we have a preference for application-oriented examples, we welcome all
-examples that demonstrate use of Ocean™ SDK tools.
+While we have a preference for application-oriented examples, we welcome all examples that
+demonstrate use of Ocean™ SDK tools.
 
-To see examples of what we are looking for, you can view our existing demos by either creating a free account on the
-[Leap™ Quantum Cloud Service](https://cloud.dwavesys.com/leap/signup/) and browsing
-our categorized [library of examples](https://cloud.dwavesys.com/leap/examples/) or by
+To see examples of what we are looking for, you can view our existing demos by either creating a
+free account on the [Leap™ Quantum Cloud Service](https://cloud.dwavesys.com/leap/signup/)
+and browsing our categorized [library of examples](https://cloud.dwavesys.com/leap/examples/) or by
 reading through the demo code repositories in [dwave-examples](https://github.com/dwave-examples).
 
 ## Steps for Contributing
 
-1. Follow GitHub's instructions for [creating a repository from a template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template).
-   Alternatively, clone this repository (or one of our [existing examples](https://github.com/dwave-examples)) as a
-   starting point from which to implement your example.
-2. Implement your example by following the instructions in the [README](README.md).
-3. [Open an issue](https://github.com/dwave-examples/template-dash/issues/new/choose) in the
-   [dwave-examples/template-dash](https://github.com/dwave-examples/template-dash) repository with a link to your example.
-
-4. To add your example, D-Wave will fork your repository. We may make a pull
-   request if we would like your approval for certain code changes.
-
-## Guidelines
-
-### Files
-
-Please make sure that your example includes the following:
-
-* `README.md`:
-    * Should be written in Markdown (and not reStructuredText).
-    * See this repository's [README](README.md).
-
-* `requirements.txt`:
-    * `dwave-ocean-sdk` should be unpinned and lower bounded.
-    * Add requirements for running your example and make sure they are either pinned to a version supported by the latest Ocean SDK release or lower bounded.
-
-* `LICENSE`:
-    * Examples should comply with the Apache 2.0 License. Please make sure that:
-        * All source and test files include a license header.
-        * The [`LICENSE`](LICENSE) file is included in your root directory.
-
-* Tests that are located in `/tests/` and discoverable through `python -m unittest discover`.
-
-Our examples are tested using CircleCI. For a list of operating systems and
+1.  Follow GitHub's instructions for
+    [creating a repository from a template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template).
+    Alternatively, clone this repository as a starting point from which to implement your example.
+
+2.  Implement your example by following these instructions:
+
+    1.  It is preferable for you to write all Python and CSS code in either new files or files that
+        contain `demo` in the name. Below is a list of `demo` files and their functionality:
+
+        *   [demo_callbacks.py](demo_callbacks.py) contains all the
+            [Dash callback functions](https://dash.plotly.com/basic-callbacks) required to run the
+            Dash app. Updates to existing callbacks and new callbacks should be made in this file.
+        *   [demo_interface.py](demo_interface.py) contains all the Dash HTML components that
+            generate the user interface (UI) for the app, including settings like sliders,
+            checkboxes, and text inputs, as well as buttons and tables. If a Dash HTML component
+            needs to be dynamically added to the UI by a Dash callback in `demo_callbacks.py`, it
+            is encouraged to add a function generating this component to `demo_interface.py` and
+            call this function from `demo_callbacks.py`.
+        *   [demo_configs.py](demo_configs.py) contains all configurations and settings for the
+            demo and is intended as a quick way to customize the demo for a specific audience or
+            use case. Add variables to this file that users may want to change; for example, titles
+            and default settings values but not evergreen labels or internal variables.
+        *   [demo.css](assets/demo.css) contains all custom CSS styling for the demo; any new CSS rules
+            should be added here or in a new file in the `/assets/` directory. Dash reads all
+            files in `/assets/` in alphabetical order so, out of the provided CSS files, `demo.css`
+            runs last and can overwrite previous styling rules.
+        *   [__demo_variables.css](assets/__demo_variables.css) contains all CSS variables.
+            It is encouraged to edit or add more CSS variables here.
+        *   [demo_enums.py](src/demo_enums.py) contains [Enum](https://docs.python.org/3/library/enum.html)
+            classes for any settings or variables that are being used frequently to avoid string
+            comparisons or other fragile code practices.
+
+    2.  All new files should be added to one of the following directories:
+        *   `/assets/` is a Dash-specific directory that must not contain subdirectories and must
+            not be renamed. Dash always reads files in this directory in alphabetical order and
+            therefore you do not need to explicitly import files from this directory. Avoid altering
+            CSS files with the word `demo` in the filename.
+        *   `/src/` should contain all functional code for the demo including solver implementations,
+            class definitions, etc. You can add subdirectories as needed.
+        *   `/static/` should contain all new static files such as images. You can add subdirectories
+            as needed.
+        *   `/tests/` should contain tests for all code found in `/src/`. All tests should be
+            discoverable through `python -m unittest discover`.
+
+    3.  Follow the [README template](README.md) to create a README that describes your example and
+        outlines how it works.
+
+3.  Once your example has been implemented,
+    [open an issue](https://github.com/dwave-examples/template-dash/issues/new/choose) in the
+    [dwave-examples/template-dash](https://github.com/dwave-examples/template-dash) repository
+    with a link to your example.
+
+When adding a contributed example, D-Wave forks your repository and may make a pull 
+request to get your approval for certain code changes.
+
+## Final Checklist
+
+- [ ] **PEP 8**: All code follows the [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide.
+If you are unsure, install and run [black](https://pypi.org/project/black/) to ensure correct formatting.
+
+- [ ] **Docstrings**: All functions contain docstrings describing what the function does and any
+arguments or return values. For more information, see the
+[Google docstrings convention](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings).
+
+- [ ] **README**: The demo contains an updated `README.md` file that follows the
+[README template](README.md) and is written in Markdown.
+
+- [ ] **Requirements**: All requirements for running the demo have been listed in `requirements.txt`
+and are either pinned to a version supported by the latest Ocean SDK release or lower bounded.
+`dwave-ocean-sdk` is unpinned and lower bounded.
+
+- [ ] **LICENSE**: The demo complies with the Apache 2.0 License and the [`LICENSE`](LICENSE) file
+is included in the root directory. All files include a license header.
+
+- [ ] **Tests**: All code included in the `/src/` directory has associated tests that are located in
+`/tests/` and discoverable through `python -m unittest discover`.
+
+- [ ] **Codespaces**: The [`.devcontainer/`](.devcontainer/) directory is included in the demo's
+root directory to ensure the demo runs in
+[GitHub Codespaces](https://docs.github.com/en/codespaces/overview).
+
+- [ ] **CircleCI**: The demo contains the [`.circleci/`](.circleci/) directory to support running
+tests in CI. Once approved, we will make sure that your example is set up on our CircleCI account.
+
+> [!NOTE]\
+> Our examples are tested using CircleCI. For a list of operating systems and
 Python versions we currently test our examples with, please take a look at [our
 documentation](https://docs.ocean.dwavesys.com/en/stable/overview/install.html).
 For more information, visit [orb-examples](https://circleci.com/developer/orbs/orb/dwave/orb-examples).
 
-The example repository should contain the [`.circleci/`](.circleci/) directory to support running tests in CI.
-Once approved, we will make sure that your example is set up on our CircleCI account.
-
-To ensure that your example runs in [GitHub Codespaces](https://docs.github.com/en/codespaces/overview),
-make sure to include the [`.devcontainer/`](.devcontainer/) directory into your example's root directory.
-
-### Code
-
-We use the [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide as a baseline.
-
-If your example is lengthy, we encourage modularity for ease of testing.
-
-### Documentation
-
-We use the [Google docstrings convention](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings).
+---
 
-Take a look at our [How to Contribute](https://docs.ocean.dwavesys.com/en/latest/contributing.html#documentation-and-comments)
-guide for more details.
+For more information about contributing, take a look at our
+[How to Contribute](https://docs.ocean.dwavesys.com/en/latest/contributing.html#documentation-and-comments)
+guide.

README.md

@@ -1 +1,123 @@
-# Dash Template
+### Interested in contributing a code example?
+
+Please take a look at our [contribution guidelines](CONTRIBUTING.md) before getting started.
+Thank you!
+
+The Dash template is intended for demos that would benefit from a user interface. This user
+interface could include settings to run and customize the problem, an interactive graphical element,
+or tables/charts to compare different solutions. This template is also useful for demos that are
+intended for a general audience, as it is more approachable for those without a technical background.
+
+<!-- Before submitting your code, please delete everything above and including this comment. -->
+<!-- The following is a README template for your new demo. -->
+
+# Demo Name
+
+Describe your demo and specify what it is demonstrating. Consider the
+following questions:
+
+* Is it a canonical problem or a real-world application?
+* Does it belong to a particular domain such as material simulation or logistics?
+* What level of Ocean proficiency does it target: beginner, advanced?
+
+A clear description allows us to properly categorize your demo.
+
+Please include a screenshot of your demo below.
+
+![Demo Example](static/demo.png)
+
+<!-- Below is boilerplate instructions to be included, as is, in the final demo. -->
+
+## Installation
+You can run this example without installation in cloud-based IDEs that support the
+[Development Containers specification](https://containers.dev/supporting) (aka "devcontainers")
+such as GitHub Codespaces.
+
+For development environments that do not support `devcontainers`, install requirements:
+
+```bash
+pip install -r requirements.txt
+```
+
+If you are cloning the repo to your local system, working in a
+[virtual environment](https://docs.python.org/3/library/venv.html) is recommended.
+
+## Usage
+Your development environment should be configured to access the
+[Leap&trade; Quantum Cloud Service](https://docs.ocean.dwavesys.com/en/stable/overview/sapi.html).
+You can see information about supported IDEs and authorizing access to your Leap account
+[here](https://docs.dwavesys.com/docs/latest/doc_leap_dev_env.html).
+
+Run the following terminal command to start the Dash app:
+
+```bash
+python app.py
+```
+
+Access the user interface with your browser at http://127.0.0.1:8050/.
+
+The demo program opens an interface where you can configure problems and submit these problems to
+a solver.
+
+Configuration options can be found in the [demo_configs.py](demo_configs.py) file.
+
+> [!NOTE]\
+> If you plan on editing any files while the app is running,
+please run the app with the `--debug` command-line argument for live reloads and easier debugging:
+`python app.py --debug`
+
+<!-- End of boilerplate. -->
+
+## Problem Description
+Give an overview of the problem you are solving in this demo.
+
+**Objectives**: define the goal this example attempts to accomplish by minimizing or maximizing
+certain aspects of the problem. For example, a production-line optimization might attempt to
+minimize the time to produce all of the products.
+
+**Constraints**: aspects of the problem, with limited or no flexibility, that must be satisfied for
+solutions to be considered feasible. For example, a production-line optimization might have a
+limitation that Machine A can only bend 10 parts per hour.
+
+## Model Overview
+The clearer your model is presented here, the more useful it will be to others. For a strong example
+of this section, see [here](https://github.com/dwave-examples/3d-bin-packing#model-overview).
+
+### Parameters
+List and define the parameters used in your model.
+
+### Variables
+List and define (including type: e.g., "binary" or "integer") the variables solved for in your model.
+
+### Expressions
+List and define any combinations of variables used for easier representations of the models.
+
+### Objective
+Mathematical formulation of the objective described in the previous section using the listed
+parameters, variables, etc.
+
+### Constraints
+Mathematical formulation of the constraints described in the previous section using the listed
+parameters, variables, etc.
+
+## Code Overview
+
+A general overview of how the code works.
+
+Include any notable parts of the code implementation:
+
+* Talk about unusual or potentially difficult parts of the code
+* Explain a code decision
+* Explain how parameters were tuned
+
+Note: there is no need to repeat everything that is already well-documented in
+the code.
+
+## References
+
+A. Person (YEAR), "An Article Title that Helped Formulate the Problem".
+[Link Title](https://example.com/)
+
+## License
+
+Released under the Apache License 2.0. See [LICENSE](LICENSE) file.