Merge branch 'preview' of https://github.com/pnp/generator-teams into…

… preview
pnp · May 10, 2022 · 302ad1b · 302ad1b
2 parents e67e64a + 88ce897
commit 302ad1b
Show file tree

Hide file tree

Showing 14 changed files with 110 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -33,7 +33,7 @@ The `yoteams-deploy` documentation and source code is found under [packages/yote
 
 ## Documentation
 
-The documentation for the generator and the generated project can be found in the [generator-teams Github repository](https://github.com/pnp/generator-teams/tree/master/docs/docs).
+The documentation for the generator and the generated project can be found in the generator-teams [Github repository](https://github.com/pnp/generator-teams/tree/master/docs/docs) or in the [documentation website](https://pnp.github.io/generator-teams).
 
 ## More information
 

diff --git a/docs/docs/contributing/minimal-path.md b/docs/docs/contributing/minimal-path.md
@@ -0,0 +1,83 @@
+# Minimal Path to Awesome
+The shortest way to prepare your local copy of the project for development and testing.
+
+# Install prerequisites
+Our prerequisites are the same as when you first [installed the Teams Generator](https://pnp.github.io/generator-teams/user-guide/setup-machine/)
+
+# Get a local version of the Teams Generator
+1. Fork this repository
+2. Clone your fork
+3. Navigate to the correct directory for the package you want to make a change to. The Teams generator is split into 3 different parts:
+    - generator-teams
+    - yoteams-build-core
+    - yoteams-deploy
+- in the command line:
+    - run `npm i` to restore dependencies
+
+    ![nmpi](../images/contributing-npminstall.png)
+
+    - run `npm run build` to build the project
+
+    ![nmprunbuild](../images/contributing-npmrunbuild.png)
+
+    - run `npm test` to run unit tests (optional this can take a while)
+
+If you installed the Generator globally using the `npm install generator-teams --global` command, we recommend that you uninstall it first, before running `npm link`    
+
+run `npm link` to install the project locally. After linking the local package, we recommend that you create a empty folder in another drive where you can run the locally installed version of the Teams generator.
+
+![no changes done](../images/contributing-nochanges.png)
+
+Now you can start with changing the generator code. (In this example we are changing the first question)
+
+![code changed](../images/contributing-dochanges.png)
+
+After changing the code, run the `npm run build` command to rebuild the project and see your changes integrated in the local version of the Teams generator.
+
+![new generator version](../images/contributing-didchanges.png)
+
+> If you renamed files:
+
+in the command line:
+- run `npm run clean` to clean up the output folder
+- run `npm run build` to rebuild the project
+- run `npm link` to reinstall the project locally. Without this step, you will get an error, when trying to start the local version of the generator.
+
+> Don't forget to add tests if you add logic.
+
+# Documentation
+
+The Microsoft Teams Generator uses [MkDocs](http://www.mkdocs.org/) to publish documentation pages. For simplicity, we recommend using the MkDocs Material Docker container which contains all dependencies installed.
+
+### Preview docs using the Docker container
+If you're using Visual Studio Code and have the Docker extension installed, you can run preview the docs using the container either by executing the `Run docs container` task, or, if you have pulled the image previously, from the Images pane by running the MkDocs container interactively. This article explains [working with Docker containers using VSCode](https://blog.mastykarz.nl/docker-containers-visual-studio-code-extension/) in more detail.
+
+More information on how to use the Visual Studio Code extension please visit [the tutorial](https://docs.microsoft.com/en-us/visualstudio/docker/tutorials/docker-tutorial)
+
+To run tasks easily from Visual Studio Code you can use the [Task explorer](https://marketplace.visualstudio.com/items?itemName=spmeesseman.vscode-taskexplorer). With this you can easily start the `run doc container`
+
+![Run docs container](../images/contributing-run-docs-container.png)
+
+Or you can start the docs container interactive, if you like to see the what's going on in an interactive screen. 
+
+![Run docs container interactive](../images/contributing-run-docs-container-interactive.png)
+
+Alternatively, you can run the container in command-line:
+
+- on macOS:
+    - run `cd ./docs` to change directory to where the docs are stored
+    - run `docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material` to start the local web server with MkDocs and view the documentation in the web browser
+- on Windows:
+    - run `docker run --rm -it -p 8000:8000 -v c:/projects/cli-microsoft365/docs:/docs squidfunk/mkdocs-material` to start the local web server with MkDocs and view the    documentation in the web browser
+
+### Preview docs using MkDocs installed on your machine.
+If you want, you can also install MkDocs on your machine. See more information about installing MkDocs on your operating system at [http://www.mkdocs.org/#installation](http://www.mkdocs.org/#installation).
+
+The Teams generator documentation currently uses mkdocs-material theme. See more information about installing mkdocs-material on your operating system at [https://squidfunk.github.io/mkdocs-material](https://squidfunk.github.io/mkdocs-material).
+
+In order to run documentation locally, you can install MkDocs with pip (the Python package manager) then install the appropriate mkdocs-material version:
+
+`pip install mkdocs mkdocs-material==7.1.7 pymdown-extensions==9.0`
+Once you have MkDocs installed on your machine, in the command line:
+
+run `cd ./docs` to change directory to where the docs are stored run `mkdocs serve` to start the local web server with MkDocs and view the documentation in the web browser
diff --git a/docs/docs/images/contributing-didchanges.png b/docs/docs/images/contributing-didchanges.png
diff --git a/docs/docs/images/contributing-dochanges.png b/docs/docs/images/contributing-dochanges.png
diff --git a/docs/docs/images/contributing-nochanges.png b/docs/docs/images/contributing-nochanges.png
diff --git a/docs/docs/images/contributing-npminstall.png b/docs/docs/images/contributing-npminstall.png
diff --git a/docs/docs/images/contributing-npmrunbuild.png b/docs/docs/images/contributing-npmrunbuild.png
diff --git a/docs/docs/images/contributing-run-docs-container-interactive.png b/docs/docs/images/contributing-run-docs-container-interactive.png
diff --git a/docs/docs/images/contributing-run-docs-container.png b/docs/docs/images/contributing-run-docs-container.png
diff --git a/docs/docs/user-guide/setup-machine.md b/docs/docs/user-guide/setup-machine.md
@@ -35,3 +35,8 @@ If you want to install preview versions of the Teams generator with this command
 ``` bash
 npm install generator-teams@preview --global
 ```
+## Possible issues
+If you get this error:
+> This generator (teams:app) requires yeoman-environment at least 3.0.0, current version is 2.10.3, try reinstalling latest version of 'yo' or use '--ignore-version-check' option
+
+and you run `npm -g outdated` you will notice that you are not running the latest version of the yeoman generator. You need to update your global package of yo using `npm install yo@latest -g`. To update to the latest version of the gulp CLI use `npm install gulp-cli@latest -g`
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -24,6 +24,7 @@ nav:
   - Contributing:
     - 'Guidelines': 'contributing/contribution-guidelines.md'
     - 'Getting started': 'contributing/getting-started.md'
+    - 'Minimal Path to Awesome': 'contributing/minimal-path.md'
   - About:
     - 'Why this generator': 'about/why-generator.md'
     - 'Telemetry': 'about/telemetry.md'

diff --git a/packages/README.md b/packages/README.md
@@ -0,0 +1,18 @@
+# Different packages
+
+To keep an a seperation of concern, we opted into having 3 seperate packages that when combined create the Microsoft Teams Apps generator
+
+## Generator-teams
+
+This is the yeoman generator that creates the scaffolding for you. Most functionality can be found in this package.
+More information can be found in the specific [readme file](https://github.com/pnp/generator-teams/tree/master/packages/generator-teams)
+
+## Yoteams-build-core
+
+This package consists of a set of Gulp tasks that is used by the Generator. They make sure the generator works as designed but hold no scaffolding logic. These are for example the build tasks.
+More information can be found in the specific [readme file](https://github.com/pnp/generator-teams/tree/master/packages/yoteams-build-core)
+
+## Yoteams-deploy
+
+This package consists of a set of Gulp tasks that will help you deploy the Teams application you created to your environment. 
+More information can be found in the specific [readme file](https://github.com/pnp/generator-teams/tree/master/packages/yoteams-deploy)
diff --git a/packages/generator-teams/README.md b/packages/generator-teams/README.md
@@ -43,7 +43,7 @@ The solution can be built using the Gulp task `build` and hosted on a local web
 
 ## yo teams Demo
 
-![Demo](docs/assets/demo.gif)
+![Demo](https://github.com/pnp/generator-teams/blob/master/docs/assets/demo.gif)
 
 ## Install
 

diff --git a/packages/yoteams-build-core/CHANGELOG.md b/packages/yoteams-build-core/CHANGELOG.md
@@ -17,7 +17,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 * Fixed issue with telemetry timeout at the end of scaffolding
 
-## [*1.6.0*]- <*2022-02-07*>
+## [*1.6.0*]- <*2022-02-17*>
 
 ### Added