Separate gulp script for docs (#6409)

.gitignore

@@ -132,7 +132,7 @@ src/Umbraco.Web.UI.Client/bower_components/*
 preserve.belle
 
 #Ignore Rule for output of generated documentation files from Grunt docserve
-src/Umbraco.Web.UI.Client/docs/api
+src/Umbraco.Web.UI.Docs/api
 src/*.boltdata/
 src/umbraco.sln.ide/*
 src/.vs/

build/build-docs.ps1

@@ -1,44 +0,0 @@
-$uenv=build/build.ps1 -get
-
-$src = "$($uenv.SolutionRoot)\src"
-$tmp = $uenv.BuildTemp
-$out = $uenv.BuildOutput
-$DocFxJson = "$src\ApiDocs\docfx.json"
-$DocFxSiteOutput = "$tmp\_site\*.*"
-
-################ Do the UI docs
-$uenv.CompileBelle()
-
-"Moving to Umbraco.Web.UI.Client folder"
-cd .\src\Umbraco.Web.UI.Client
-
-"Generating the docs and waiting before executing the next commands"
-& gulp docs | Out-Null
-
-# change baseUrl
-$BaseUrl = "https://our.umbraco.com/apidocs/v8/ui/"
-$IndexPath = "./docs/api/index.html"
-(Get-Content $IndexPath).replace('location.href.replace(rUrl, indexFile)', "`'" + $BaseUrl + "`'") | Set-Content $IndexPath
-
-# zip it
-& $uenv.BuildEnv.Zip a -tzip -r "$out\ui-docs.zip" "$src\Umbraco.Web.UI.Client\docs\api\*.*"
-
-
-################ Do the c# docs
-
-# Build the solution in debug mode
-$SolutionPath = Join-Path -Path $src -ChildPath "umbraco.sln"
-#$uenv.CompileUmbraco()
-
-#restore nuget packages
-$uenv.RestoreNuGet()
-
-# run DocFx
-$DocFx = $uenv.BuildEnv.DocFx
-
-Write-Host "$DocFxJson"
-& $DocFx metadata $DocFxJson
-& $DocFx build $DocFxJson
-
-# zip it
-& $uenv.BuildEnv.Zip a -tzip -r "$out\csharp-docs.zip" $DocFxSiteOutput

build/build.ps1

@@ -456,25 +456,24 @@
   $ubuild.DefineMethod("PrepareAngularDocs",
   {
     Write-Host "Prepare Angular Documentation"
-
+    
     $src = "$($this.SolutionRoot)\src"
-      $out = $this.BuildOutput
-
-    $this.CompileBelle()
-
-    "Moving to Umbraco.Web.UI.Client folder"
-    cd .\src\Umbraco.Web.UI.Client
+    $out = $this.BuildOutput
+	  
+    "Moving to Umbraco.Web.UI.Docs folder"
+    cd ..\src\Umbraco.Web.UI.Docs
 
     "Generating the docs and waiting before executing the next commands"
-    & gulp docs | Out-Null
+	& npm install
+    & npx gulp docs
 
     # change baseUrl
     $BaseUrl = "https://our.umbraco.com/apidocs/v8/ui/"
-    $IndexPath = "./docs/api/index.html"
+    $IndexPath = "./api/index.html"
     (Get-Content $IndexPath).replace('location.href.replace(rUrl, indexFile)', "`'" + $BaseUrl + "`'") | Set-Content $IndexPath
 
     # zip it
-    & $this.BuildEnv.Zip a -tzip -r "$out\ui-docs.zip" "$src\Umbraco.Web.UI.Client\docs\api\*.*"
+    & $this.BuildEnv.Zip a -tzip -r "$out\ui-docs.zip" "$src\Umbraco.Web.UI.Docs\api\*.*"
   })
 
   $ubuild.DefineMethod("Build",

src/Umbraco.Web.UI.Client/docs/src/api/index.ngdoc

@@ -1,19 +0,0 @@
-@ngdoc overview
-@name Umbraco 7 JS documentation 
-@description
-
-#Umbraco Backoffice UI API documentation
-
-This documentation relates to the angular, js, css and less APIs for developing back office components
-
-##Getting started
-The current app is built, following conventions from angularJs and bootstrap. To get started with the applicaton you will need to atleast know the basics of these frameworks 
-
-###AngularJS
-- Excellent introduction videos on http://www.egghead.io/
-- Official guide at: http://docs.angularjs.org/guide/
-
-
-
-
-

src/Umbraco.Web.UI.Client/gulp/config.js

@@ -41,7 +41,7 @@ module.exports = {
                     "./src/views/**/*.{directive,component}.js"
                 ],
                 out: "umbraco.directives.js"
-            },
+            }
         },
 
         //selectors for copying all views into the build

src/Umbraco.Web.UI.Client/gulp/tasks/docserve.js

@@ -1,10 +0,0 @@
-'use strict';
-
-var config = require('../config');
-var gulp = require('gulp');
-var runSequence = require('run-sequence');
-
-// Docserve - build and open the back office documentation
-gulp.task('docserve', function(cb) {
-    runSequence('docs', 'connect:docs', 'open:docs', cb);
-});

src/Umbraco.Web.UI.Client/package.json

@@ -4,8 +4,7 @@
     "test": "karma start test/config/karma.conf.js --singlerun",
     "build": "gulp build",
     "dev": "gulp dev",
-    "fastdev": "gulp fastdev",
-    "docs": "gulp docs"
+    "fastdev": "gulp fastdev"
   },
   "dependencies": {
     "ace-builds": "1.4.2",
@@ -55,13 +54,10 @@
     "gulp-clean-css": "4.0.0",
     "gulp-cli": "^2.0.1",
     "gulp-concat": "2.6.1",
-    "gulp-connect": "5.6.1",
     "gulp-eslint": "^5.0.0",
     "gulp-imagemin": "^4.1.0",
     "gulp-less": "4.0.1",
-    "gulp-ngdocs": "0.3.0",
     "gulp-notify": "^3.0.0",
-    "gulp-open": "3.0.1",
     "gulp-postcss": "8.0.0",
     "gulp-rename": "1.4.0",
     "gulp-sort": "2.0.0",

src/Umbraco.Web.UI.Docs/README.md

@@ -0,0 +1,14 @@
+# Umbraco Backoffice UI API Documentation
+
+This project builds the documentation for the UI of the Umbraco backoffice, it is published on Our Umbraco in the "Reference" section of the documentation.
+
+In order to build the documentation, please follow the following two steps:
+
+```
+npm install
+npx gulp docs
+```
+
+After this, you should have an `api` directory which contains index.html. 
+
+In order to check if the documentation works properly, you would need to run the `api` directory in a webserver. On Windows, this can be accomplished by opening the `api` directory in [Visual Studio Code](https://code.visualstudio.com/) and running it with the [IIS Express plugin](https://marketplace.visualstudio.com/items?itemName=warren-buckley.iis-express).

src/Umbraco.Web.UI.Docs/gulpfile.js

@@ -1,6 +1,7 @@
 'use strict';
 
-var config = require('../config');
+
+var config = require('../Umbraco.Web.UI.Client/gulp/config');
 var gulp = require('gulp');
 
 var connect = require('gulp-connect');
@@ -16,28 +17,28 @@ gulp.task('docs', [], function (cb) {
         html5Mode: false,
         startPage: '/api',
         title: "Umbraco Backoffice UI API Documentation",
-        dest: 'docs/api',
-        styles: ['docs/umb-docs.css'],
+        dest: './api',
+        styles: ['./umb-docs.css'],
         image: "https://our.umbraco.com/assets/images/logo.svg"
     }
 
     return gulpDocs.sections({
         api: {
-            glob: ['src/common/**/*.js', 'docs/src/api/**/*.ngdoc'],
+            glob: ['../Umbraco.Web.UI.Client/src/common/**/*.js', './src/api/**/*.ngdoc'],
             api: true,
-            title: 'API Documentation'
+            title: 'UI API Documentation'
         }
     })
     .pipe(gulpDocs.process(options))
-    .pipe(gulp.dest('docs/api'));
+    .pipe(gulp.dest('./api'));
     cb();
 });
 
 gulp.task('connect:docs', function (cb) {
     connect.server({
-        root: 'docs/api',
+        root: './api',
         livereload: true,
-        fallback: 'docs/api/index.html',
+        fallback: './api/index.html',
         port: 8880
     });
     cb();

src/Umbraco.Web.UI.Docs/package.json

@@ -0,0 +1,14 @@
+{
+  "private": true,
+  "scripts": {
+    "docs": "gulp docs",
+    "start": "gulp docs",
+    "default": "gulp docs"
+  },
+  "devDependencies": {
+    "gulp": "^3.9.1",
+    "gulp-connect": "5.6.1",
+    "gulp-ngdocs": "0.3.0",
+    "gulp-open": "3.0.1"
+  }
+}