From 296b9992b8dee4bf632d9bbfadb78f94bbb4b1c1 Mon Sep 17 00:00:00 2001 From: Sankalp Sanand Date: Fri, 18 Feb 2022 01:40:39 -0500 Subject: [PATCH] Basic structure to write a beginner tutorial (#114) * Added basic structure of how the tutorial will be written * Added concepts section * New file creation * updated new tutorial * Removed a non template file * Updated changelog and version * Updated notebook and added it to tutorials.rst * Converted guide to rst file and linked in tutorials.rst * Small update * Updated changelog * Updated changelog and version * Changelog format fix * edits * formatting Co-authored-by: Will Cunningham --- CHANGELOG.md | 8 ++++++ VERSION | 2 +- doc/source/tutorials/tutorial_guide.rst | 36 +++++++++++++++++++++++++ doc/source/tutorials/tutorials.rst | 2 +- 4 files changed, 46 insertions(+), 2 deletions(-) create mode 100644 doc/source/tutorials/tutorial_guide.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index cdae08f65..a65223369 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.24.21] - 2022-02-18 + +### Added + +- RST document describing the expectations from a tutorial. + ## [0.24.20] - 2022-02-17 ### Added @@ -189,6 +195,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - UI: display error message on failed status for lattice and electron ### Changed + - UI: re-order sidebar sections according to latest figma designs - UI: update favicon - UI: remove dispatch id from tab title @@ -196,6 +203,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - UI: adjust theme text primary and secondary colors ### Fixed + - UI: auto-refresh result state on initial render of listing and graph pages - UI: graph layout issues: truncate long electron/param names diff --git a/VERSION b/VERSION index af8eba671..c1aa780a5 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.24.20 +0.24.21 diff --git a/doc/source/tutorials/tutorial_guide.rst b/doc/source/tutorials/tutorial_guide.rst new file mode 100644 index 000000000..b6571b36a --- /dev/null +++ b/doc/source/tutorials/tutorial_guide.rst @@ -0,0 +1,36 @@ +**************************** +Tutorial Writing Guide +**************************** + +This guide covers best practices for Covalent tutorials. These principles are indended to guide but not constrain the author. + +Set the scope +------------- + +Good tutorials are small and self-contained. They do not overcomplicate things and cater to a mixed audience. Any examples highlighted should be straightforward and friendly to beginners. + +Introduce the example +--------------------- + +Introduce background material and describe what we will be trying to achieve in the tutorial. Separate the logical components and show what purpose each of them serves. + +Prototype the solution +---------------------- + +Write code with commented explanations wherever necessary. Write it without Covalent, in a functional manner, where it is clear what each of the components is doing in the context of the example. + +Run the workflows +----------------- + +Add decorators to the functions without changing their definitions. Show representative screenshots of the UI to help readers understand the problem being solved. A good tutorial also provides typical input parameters and the corresponding typical runtimes. + +Analyze the results +------------------- + +View the results in the Covalent UI, and query them programatically as well. Summarize the findings using a meaningful plot or chart. Discuss the metadata returned in the result object. + + +Discuss the concepts +-------------------- + +Highlight how different components of Covalent are used to accomplish objectives or to obey constraints. diff --git a/doc/source/tutorials/tutorials.rst b/doc/source/tutorials/tutorials.rst index 58bd86de0..5086b8fbd 100644 --- a/doc/source/tutorials/tutorials.rst +++ b/doc/source/tutorials/tutorials.rst @@ -13,4 +13,4 @@ The following tutorials demonstrate examples of how Covalent is used in real-wor --------------------------------- -Do you use Covalent in an interesting project? Contribute a tutorial on `GitHub `_. +Do you use Covalent in an interesting project? Contribute a tutorial on `GitHub `_. To get started, check out the :doc:`guide `.