Updating docs

README.md

@@ -9,50 +9,22 @@ For more information see the [Code of Conduct FAQ](https://opensource.microsoft.
 
 <hr>
 
-# oufr-dev-docs - [Fabric](https://github.com/OfficeDev/office-ui-fabric-react) docs repository
+# [office-ui-fabric-react](https://github.com/OfficeDev/office-ui-fabric-react) documentation repository
 
-This repository is setup in a way so that the business logic of generating the documentation files is separated from the actually generated files for the purpose of keeping a clean git history and relative to the changes that will occur daily for the docs part and only occasionally for the implementation code part. This is achieved by keeping these two concerns on different branches. `master` branch holds all the business logic and `staging` with `live` branches are auto updated in parallel by a [scheduled pipeline](https://github.com/MicrosoftDocs/oufr-dev-docs/blob/master/config/azure-pipelines/update-docs.yaml) with the files generated by using the code on the master branch.
+## Overview
 
-In order to make changes to the files generation logic, first step is to setup the environment
+This repository provides the necessary documentation files that are published by the DocFX pipeline on docs.microsoft.com portal resulting in an API reference along with some overview and examples documentation for the Fabric React controls library. You can see the end result [here](https://docs.microsoft.com/en-us/javascript/api/getstarted/getstartedpage?view=office-ui-fabric-react-latest).
 
-### Local development setup
+## Repository structure
 
-1. Clone the repo using the following command.
+The repo setup is done in a way so that the business logic of generating the documentation files is separated from the actually generated files. The main reason of this is to keep a clean git history and also relative to the changes that will occur often (daily) for the documentation part and only occasionally for the implementation code part. This is achieved by keeping these two concerns on different branches. `master` branch holds all the business logic and `staging` with `live` branches are auto updated in parallel by a scheduled task with the files generated from using the implementation code on the `master` branch.
 
-   ```
-   git clone https://github.com/MicrosoftDocs/oufr-dev-docs.git
-   ```
+## Automation pipeline
 
-2. Install the main dependencies for the project to run.
+To understand better what the scheduled task is doing, [here](dev-docs/PIPELINE_FLOW.md) is a detailed walk-through of all the stages and their steps. Additionally, the business logic code has a considerable amount of comments throughout all the files.
 
-   ```
-   npm install
-   ```
+## Contributing
 
-3. Install the latest versions of `office-ui-fabric-react` and `@uifabric/fabric-website`.  
-   Note: this are not part of main dependency install run because we want the latest versions in the pipeline to generate most up to date docs. DO NOT COMMIT the changes in this step done to `package.json` and `package-lock.json` files.
+⚠️⚠️⚠️ This repo is automatically updating its `live` and `staging` branches, so submitting documentation fixes will not be helpful because the next day after the automation pipeline updates the files again your changes would be discarded. Instead, recommended way of submitting fixes is to go and submit a PR directly in the Fabric repository here: [office-ui-fabric-react](https://github.com/OfficeDev/office-ui-fabric-react). Same thing in regards to submitting issues. Because the repo is auto updating itself, the issues backlog is almost never checked by any developer, so instead go and submit an issue in the Fabric issue backlog.
 
-   ```
-   npm run install-deps
-   ```
-
-4. Run the initial build command which is necessary for the next step.
-
-   ```
-   npm run build
-   ```
-
-5. Following step needs to be run only once when starting local developer work. This will download all `api.json` files and save them in the `input` folder that is not tracked by git so it does not need to be committed during development.
-   ```
-   npm run download-api-files
-   ```
-
-### Local development flow
-
-After running these steps you are ready to go and make changes with the business logic and run only one command (with one exception described below) every time when you want to verify your changes:
-
-```
-npm run local
-```
-
-**_Exception:_** in case you make changes to the logic of downloading the `api.json` files located [here](https://github.com/MicrosoftDocs/oufr-dev-docs/blob/master/src/downloadApiFiles.ts) you will need to rerun steps 4 and 5 from the setup above and then `npm run local`.
+The `master` branch contains only the generation of documentation files logic so any changes there need to be done very careful and with the according approval of repo maintainers. In case you consider that your changes will improve in any way the generation logic [here](dev-docs/CONTRIBUTING.md) is some helpful tips on how to setup the working environment.

config/azure-pipelines/update-docs.yaml

@@ -25,18 +25,18 @@ steps:
     verbose: false
 
 - task: Npm@1
-  displayName: 'npm run build'
+  displayName: 'npm install OUFR and @uifabric/fabric-website latest version'
   inputs:
     command: custom
     verbose: false
-    customCommand: run build
+    customCommand: install --save-dev office-ui-fabric-react @uifabric/fabric-website
 
 - task: Npm@1
-  displayName: 'npm install OUFR and @uifabric/fabric-website latest version'
+  displayName: 'npm run build'
   inputs:
     command: custom
     verbose: false
-    customCommand: install --save-dev office-ui-fabric-react @uifabric/fabric-website
+    customCommand: run build
 
 # Extract office-ui-fabric-react package version and write it in a file
 # so it can be used in the release pipeline to keep record of each update.

dev-docs/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing
+
+In order to make changes to the files generation logic follow the steps bellow for your inner loop.
+
+## Local development setup
+
+1. Clone the repo using the following command.
+
+   ```
+   git clone https://github.com/MicrosoftDocs/oufr-dev-docs.git
+   ```
+
+2. Install the main dependencies for the project to run.
+
+   ```
+   npm install
+   ```
+
+3. Install the latest versions of `office-ui-fabric-react` and `@uifabric/fabric-website`.  
+   Note: this are not part of main dependency install run because we want the latest versions in the pipeline to generate most up to date docs. ️️⚠️ DO NOT COMMIT the changes in this step done to `package.json` and `package-lock.json` files.
+
+   ```
+   npm run install-deps
+   ```
+
+4. Run the initial build command which is necessary for the next step.
+
+   ```
+   npm run build
+   ```
+
+5. Following step needs to be run only once when starting local developer work. This will download all `api.json` files and save them in the `input` folder that is not tracked by git so it does not need to be committed during development.
+
+   ```
+   npm run download-api-files
+   ```
+
+## Local development flow
+
+1. After running the steps above you are ready to go and make changes in the business logic and run only one command (with one exception described below) every time when you want to verify your changes:
+
+   ```
+   npm run local
+   ```
+
+   **_Exception:_** in case you make changes to the logic of downloading the `api.json` files located [here](https://github.com/MicrosoftDocs/oufr-dev-docs/blob/master/src/downloadApiFiles.ts) you will need to rerun steps 4 and 5 from the setup above and then `npm run local`.
+
+   This command runs under the hood several other scripts so you might see some output in the console from different scripts being invoked.
+
+   The end result of it will be tge documentation files outputted in the `office-ui-fabric-react` folder that relates to documentation itself and in the `config` folder that relates to the `api-documenter` config file.
+
+   ❕**NOTE:** files generated are git ignored, so in order to be able to verify the changes to documentation files or the `api-documenter` config file that would result from your logic changes, you would need to comment out related lines in the `.gitignore` file before your changes and make the first run after which you should temporarily commit the generated files, ❗️❗️❗️ BUT ❗️❗️❗️ very important to remember to remove them along with un-commenting the `.gitignore` changes before pushing it to the remote. After the first run and committing the generated files, any subsequent run after any of your logic changes will be reflected in the git diff.
+
+2. When you feel like your changes are good to be pushed to the remote repository, please don't forget to remove the generated files and revert the changes in the `.gitignore` file described in the `NOTE` paragraph above.
+
+   After doing that, you can push changes to the master and you will be able to see the [pipeline](https://uifabric.visualstudio.com/fabricpublic/_build?definitionId=107) described [here](PIPELINE_FLOW.md) triggered and after a successful [release](https://uifabric.visualstudio.com/fabricpublic/_release?_a=releases&view=mine&definitionId=1) deployment, a DocFX publish build will be triggered that can be accessed on their [portal](https://ops.microsoft.com/#/). To be able to access the `oufr-dev-docs` DocFX publish results you most likely will need to sign in with your Github account and also be added as a contributor or repository owner to this repository. It's an important part in verifying if your changes are validated against their strict formatting of yaml and markdown files that are published.
+
+   To verify your changes on the `docs.microsoft` portal you can navigate to the published `staging` branch following [this link](https://review.docs.microsoft.com/en-us/javascript/api/getstarted/getstartedpage?view=office-ui-fabric-react-latest&branch=staging) right after the DocFX publish build has successfully finished. This branch is available to Microsoft employees only and is not going to the `live` branch that is publicly available until next morning after a scheduled run. So make sure at the end of the day you have something that can be published and it looks nice 😊.

dev-docs/PIPELINE_FLOW.md

@@ -0,0 +1,40 @@
+# Pipeline flow
+
+The flow of auto updating the documentation consists of 2 stages and is set to happen on a scheduled basis from Monday to Friday at 8:00am. Here is a detailed overview of how it happens:
+
+1. The build definition yaml file is located [here](https://github.com/MicrosoftDocs/oufr-dev-docs/blob/master/config/azure-pipelines/update-docs.yaml) and is basically the starting point of the automation pipeline (stage 1) that contains the schedule trigger and all necessary steps to generate the documentation files and publish them as an Azure build artifact. [Here](https://uifabric.visualstudio.com/fabricpublic/_build?definitionId=107) is where that build definition gets consumed and runs the automation. An overview of what happens during this build can be represented with these steps:
+
+   - First few tasks are just to setup the environment like:
+
+     1. `npm install`
+     2. `npm install --save-dev office-ui-fabric-react @uifabric/fabric-website` used to get some documentation that is published with these packages
+     3. `npm run build`
+
+   - Next task is simply extracting the version of the `office-ui-fabric-react` package and write it to a file that is going to be used later to help keep track of update history.
+
+   - We download all the `api.json` files that are uploaded to an Azure blob storage every time a release of the Fabric packages happen. These are the core files that the documentation gets generated from.
+
+   - Before generating the main yaml files that are outputted by the `api-ducumenter` in the next step we need to generate a config file for it that will represent the navigation structure on the left side that mirrors the one of the Fabric website. During this steps we also generate some overview and example files for each Fabric control and also the GetStartedPage and ResourcesPage. The gist of what happens during this step is:
+
+     1. Create the GetStartedPage and the ResourcesPage by glueing several markdown files for each from the fabric-website package that we installed during the setup step.
+     2. Create Overview markdown files for each fabric control that are again the result of glueing the Dos, Donts and Overview markdown files that we get from the office-ui-fabric-react package that we installed during the setup step.
+     3. Create some example files for each fabric control that are simply some iframe windows to the deploy links that are generated after each successful PR merge into Fabric repo.
+     4. Create the config file that is consumed by the `api-documenter` that will include the above mentioned created files and also provide a defined structure of how the API items should be filtered during the next step.
+
+   - Run the `api-documenter` now that we have teh `api.json` files and the config file ready. This will output to a specified directory all API yaml files plus a `toc.yml` file that is generated following the structure of the config file we provided.
+
+   - Next few steps are just gathering all the generated files and publish them as build artifacts that we will consume them in the next stage of the automation process.
+
+2. The release pipeline is located [here](https://uifabric.visualstudio.com/fabricpublic/_release?_a=releases&view=mine&definitionId=1) and represents the `stage 2` that is nothing more than saving the new generated files in the first stage to the corresponding branches of the `oufr-dev-docs` repository. Here is what happens in parallel for the `staging` and `live` branches:
+
+   - Download the build artifacts from the first stage (once in the beginning).
+
+   - Delete the old documentation files from their final location (same for each branch).
+
+   - Copy the downloaded files into the location we cleaned up in the previous step (same for each branch).
+
+   - Add a new line in the `FABRIC-VERSION` file to mark the version of the office-ui-fabric-react package used in this run. This is done for history reasons plus to avoid an error in the next step when there are no changes to commit (same for each branch).
+
+   - Commit the changes (same for each branch).
+
+   - Push the changes to the remote repository (same for each branch).

src/categories.ts

@@ -1,3 +1,6 @@
+// These object is a hard copy of the app definition object in the @uifabric/fabric-website package.
+// TODO: needs to have one source of truth so that it's always up to date.
+
 export const categories = {
   'Basic Inputs': {
     Button: {},

tsconfig.json

@@ -12,7 +12,7 @@
     "lib": [
       "es2015",
       "dom"
-    ],
+    ]
   },
   "include": [
     "src"