From 963eaa392259e11b7e769ae36e6ca8012ed4e869 Mon Sep 17 00:00:00 2001 From: john gravois Date: Thu, 27 Sep 2018 10:55:13 -0700 Subject: [PATCH 1/2] docs(:bug:): ensure sticky links are flagged as active in production ISSUES CLOSED: #284 --- .travis.yml | 2 +- docs/acetate.config.js | 8 ++++---- docs/build-typedoc.js | 4 ++-- docs/src/_layout.html | 16 ++++++++-------- docs/src/api/_declaration.html | 14 +++++++------- docs/src/api/_layout.html | 16 ++++++++-------- docs/src/api/_package.html | 4 ++-- docs/src/api/index.html | 4 ++-- docs/src/guides/_layout.html | 2 +- docs/src/index.html | 4 ++-- docs/src/js/api-search.js | 3 +-- package.json | 13 +++++++------ 12 files changed, 45 insertions(+), 45 deletions(-) diff --git a/.travis.yml b/.travis.yml index 5e27a92aef..fa96c60afd 100644 --- a/.travis.yml +++ b/.travis.yml @@ -18,7 +18,7 @@ deploy: github_token: $GITHUB_TOKEN # Set in travis-ci.org dashboard on: branch: master - local-dir: docs/build + local-dir: docs/build/arcgis-rest-js target_branch: gh-pages before_deploy: - npm run docs:build diff --git a/docs/acetate.config.js b/docs/acetate.config.js index 9dbcfe26f4..6c09b50e97 100644 --- a/docs/acetate.config.js +++ b/docs/acetate.config.js @@ -2,10 +2,8 @@ const path = require("path"); const fs = require("fs"); const { inspect } = require("util"); const _ = require("lodash"); -const slug = require("slug"); const IS_DEV = process.env.ENV !== "prod"; -const BASE_URL = process.env.ENV === "prod" ? "/arcgis-rest-js" : ""; module.exports = function(acetate) { /** @@ -13,12 +11,14 @@ module.exports = function(acetate) { * default layout. */ acetate.load("**/*.+(html|md)", { + basePath: "arcgis-rest-js", metadata: { layout: "_layout:main" } }); - acetate.load("js/*", { + acetate.load("js/index.js", { + basePath: "arcgis-rest-js", metadata: { layout: false, prettyUrl: false @@ -26,7 +26,6 @@ module.exports = function(acetate) { }); acetate.metadata("**/*", { - baseUrl: BASE_URL, isDev: IS_DEV }); @@ -110,6 +109,7 @@ module.exports = function(acetate) { * start looking for changes and we can listen for the events later. */ acetate.load("typedoc.json", { + basePath: "arcgis-rest-js", metadata: { layout: false, prettyUrl: false diff --git a/docs/build-typedoc.js b/docs/build-typedoc.js index 00573464b7..c8dc7ff214 100644 --- a/docs/build-typedoc.js +++ b/docs/build-typedoc.js @@ -138,7 +138,7 @@ const md = new MarkdownIt(); */ return declarations.map(declaration => { const abbreviatedPackageName = declaration.package.replace("arcgis-rest-", "") - const src = `api/${abbreviatedPackageName}/${declaration.name}.html`; + const src = `arcgis-rest-js/api/${abbreviatedPackageName}/${declaration.name}.html`; let children; if (declaration.children) { @@ -207,7 +207,7 @@ const md = new MarkdownIt(); .uniq() .reduce((packages, package) => { const abbreviatedPackageName = package.replace("arcgis-rest-", "") - const src = `api/${abbreviatedPackageName}.html`; + const src = `arcgis-rest-js/api/${abbreviatedPackageName}.html`; const pkg = require(`${process.cwd()}/packages/${package}/package.json`); packages.push({ diff --git a/docs/src/_layout.html b/docs/src/_layout.html index ff03668de0..636f69297a 100644 --- a/docs/src/_layout.html +++ b/docs/src/_layout.html @@ -9,7 +9,7 @@ {% endif %} - + {% block css %}{% endblock %} @@ -18,8 +18,8 @@ @@ -32,11 +32,11 @@

ArcGIS REST JS

- ArcGIS REST JS + ArcGIS REST JS
@@ -44,11 +44,11 @@

ArcGIS REST JS

- ArcGIS REST API JavaScript Client + ArcGIS REST API JavaScript Client
diff --git a/docs/src/api/_declaration.html b/docs/src/api/_declaration.html index 78aa0163d0..102b64cce3 100644 --- a/docs/src/api/_declaration.html +++ b/docs/src/api/_declaration.html @@ -16,9 +16,9 @@ {%- endif -%} {%- if type.type === 'reference' and type.id and API_TOOLS.findById(data.typedoc, type.id) -%} - {{type.name}} + {{type.name}} {%- elif API_TOOLS.findByName(data.typedoc, type.name) -%} - {{type.name}} + {{type.name}} {%- elif type.type === 'reference' -%} {{type.name}} {%- endif -%} @@ -27,7 +27,7 @@ function({{ @signatureParams(type.declaration.signatures[0].parameters) }}) : {{@type(type.declaration.signatures[0].type)}} {%- elif type.type === 'reflection' and type.declaration.id and API_TOOLS.findById(data.typedoc, type.declaration.id) -%} {% set declaration = API_TOOLS.findById(data.typedoc, type.declaration.id) %} - {{declaration.name}} + {{declaration.name}} {%- elif type.type === 'reflection' and type.declaration and type.declaration.indexSignature -%} {% for signature in type.declaration.indexSignature %} {% for param in signature.parameters%}[key: {{@type(param.type)}}]: {% endfor %}{{@type(signature.type)}} @@ -394,11 +394,11 @@

Implements

{% for implementedType in implementedTypes %} {% if implementedType.id %} {% set base = API_TOOLS.findById(data.typedoc, implementedType.id) %} -
  • {{base.name}}
    • +
  • {{base.name}}
    • {% elif implementedType.name %} {% set base = API_TOOLS.findByName(data.typedoc, implementedType.name) %} {% if base %} -
  • {{base.name}}
    • +
  • {{base.name}}
    • {% elif implementedType.name %}
  • {{base.name}}
    • {% endif %} @@ -413,11 +413,11 @@

    Extends

    {% for extendedType in extendedTypes %} {% if extendedType.id %} {% set base = API_TOOLS.findById(data.typedoc, extendedType.id) %} -
  • {{base.name}}
    • +
  • {{base.name}}
    • {% elif extendedType.name %} {% set base = API_TOOLS.findByName(data.typedoc, extendedType.name) %} {% if base %} -
  • {{base.name}}
    • +
  • {{base.name}}
    • {% elif extendedType.name %}
  • {{base.name}}
    • {% endif %} diff --git a/docs/src/api/_layout.html b/docs/src/api/_layout.html index 4e790f0956..53a606b06f 100644 --- a/docs/src/api/_layout.html +++ b/docs/src/api/_layout.html @@ -3,32 +3,32 @@ {% block scripts %} - - - + + + - + {% endblock %} {% block main %}
    - +
      {% for package in data.typedoc.packages %}
    • - {% link baseUrl + package.pageUrl, package.pkg.name, class="tsd-kind-icon" %} + + {% link package.pageUrl, package.pkg.name, class="tsd-kind-icon" %}
        {% for declaration in package.declarations %} - + {% endfor %}
      • diff --git a/docs/src/api/_package.html b/docs/src/api/_package.html index 40a0b8bb61..f973826872 100644 --- a/docs/src/api/_package.html +++ b/docs/src/api/_package.html @@ -1,5 +1,5 @@ Version {{pkg.version}} -

      {% link baseUrl + url, pkg.name, class="tsd-kind-icon" %}

      +

      {% link url, pkg.name, class="tsd-kind-icon" %}

      {{pkg.description}}

      npm install:

      {% npmInstallCmd pkg %}
      @@ -8,6 +8,6 @@

      CDN:

        {% for declaration in declarations %} -
      • {% link baseUrl + declaration.pageUrl, declaration.name, class="tsd-kind-icon" %}
        • +
      • {% link declaration.pageUrl, declaration.name, class="tsd-kind-icon" %}
        • {% endfor %}
      diff --git a/docs/src/api/index.html b/docs/src/api/index.html index f371703184..0019addafe 100644 --- a/docs/src/api/index.html +++ b/docs/src/api/index.html @@ -6,7 +6,7 @@

      Packages

      {% for package in data.typedoc.packages %}
      Version {{package.pkg.version}} -

      {% link baseUrl + package.pageUrl, package.pkg.name, class="tsd-kind-icon" %}

      +

      {% link package.pageUrl, package.pkg.name, class="tsd-kind-icon" %}

      {{package.pkg.description}}

      npm install:

      {% npmInstallCmd package.pkg %}
      @@ -15,7 +15,7 @@

      CDN:

        {% for declaration in package.declarations %} -
      • {% link baseUrl + declaration.pageUrl, declaration.name, class="tsd-kind-icon" %}
        • +
      • {% link declaration.pageUrl, declaration.name, class="tsd-kind-icon" %}
        • {% endfor %}
      diff --git a/docs/src/guides/_layout.html b/docs/src/guides/_layout.html index c603b7d6df..3e1a7ad95a 100644 --- a/docs/src/guides/_layout.html +++ b/docs/src/guides/_layout.html @@ -8,7 +8,7 @@
    • {{section.name}}
        • {% for item in section.items %} -
      • {% link baseUrl + item.url, item.title %}
        • +
      • {% link item.url, item.title %}
        • {% endfor %}
      {% endfor %} diff --git a/docs/src/index.html b/docs/src/index.html index 8457cc2f6d..18c6df5d25 100644 --- a/docs/src/index.html +++ b/docs/src/index.html @@ -4,8 +4,8 @@

      ArcGIS REST JS

      Compact, modular JavaScript wrappers for the ArcGIS REST API.

      - {% link baseUrl + "/guides/", "Get Started", class="btn btn-large btn-clear-white" %} - {% link baseUrl + "/api/", "API Reference", class="btn btn-large btn-clear-white" %} + {% link "./guides/", "Get Started", class="btn btn-large btn-clear-white" %} + {% link "./api/", "API Reference", class="btn btn-large btn-clear-white" %}
    diff --git a/docs/src/js/api-search.js b/docs/src/js/api-search.js index 1ec87847a2..b989600808 100644 --- a/docs/src/js/api-search.js +++ b/docs/src/js/api-search.js @@ -31,7 +31,6 @@ Vue.component("api-search", { searchTerm: "" }; }, - props: ['baseUrl'], methods: { highlightText: function(text, matches) { return matches @@ -64,7 +63,7 @@ Vue.component("api-search", { return { title: this.highlightText(result.item.title, result.matches), icon: result.item.icon, - url: this.baseUrl + result.item.url + url: result.item.url }; }); }, diff --git a/package.json b/package.json index 7f79ccaa10..0b61e9c9d3 100644 --- a/package.json +++ b/package.json @@ -84,20 +84,21 @@ "test:node:debug": "inspect jasmine --config=jasmine.json", "test:ci": "npm run lint && npm run test:node && npm run test:chrome:ci && npm run test:firefox", "test:all": "npm run test:node && npm run test:firefox && npm run test:chrome", - "docs:build": "rimraf docs/build && npm run docs:typedoc && npm run docs:build:acetate && npm run docs:build:sass && npm run docs:build:images", + "docs:build": "rimraf docs/build && npm run docs:typedoc && npm run docs:build:acetate && npm run docs:build:sass && npm run docs:build:images && npm run docs:build:js", "docs:build:acetate": "ENV=prod acetate build --config docs/acetate.config.js", - "docs:build:sass": "node-sass --output docs/build/css --source-map true --source-map-contents docs/src/sass", - "docs:build:images": "cpx \"docs/src/**/*.{png,jpg,jpeg,gif,svg,webm,ogg}\" docs/build", + "docs:build:sass": "node-sass --output docs/build/arcgis-rest-js/css --source-map true --source-map-contents docs/src/sass", + "docs:build:images": "cpx \"docs/src/**/*.{png,jpg,jpeg,gif,svg,webm,ogg}\" docs/build/arcgis-rest-js", + "docs:build:js": "cpx \"docs/src/**/{api-search,nav-toggle}.js\" docs/build/arcgis-rest-js", "docs:deploy": "npm run docs:build && node support/deploy-doc-site.js", "docs:typedoc": "node docs/build-typedoc.js", "docs:dev:typedoc": "onchange -v 'packages/*/src/**/*.ts' -- npm run docs:typedoc", "predocs:serve": "npm run docs:typedoc", "docs:serve": "rimraf docs/build && concurrently \"npm run docs:dev:js\" \"npm run docs:dev:images\" \"npm run docs:dev:acetate\" \"npm run docs:dev:sass\" \"npm run docs:dev:typedoc\"", - "docs:dev:images": "cpx \"docs/src/**/*.{png,jpg,jpeg,gif,svg,webm,ogg}\" docs/build -w", + "docs:dev:images": "cpx \"docs/src/**/*.{png,jpg,jpeg,gif,svg,webm,ogg}\" docs/build/arcgis-rest-js -w", "docs:dev:acetate": "acetate server --log=debug --config docs/acetate.config.js", "predocs:dev:sass": "npm run docs:build:sass", - "docs:dev:sass": "node-sass --watch --recursive --output docs/build/css --source-map true --source-map-contents docs/src/sass", - "docs:dev:js": "cpx \"docs/src/**/{api-search,nav-toggle}.js\" docs/build -w", + "docs:dev:sass": "node-sass --watch --recursive --output docs/build/arcgis-rest-js/css --source-map true --source-map-contents docs/src/sass", + "docs:dev:js": "cpx \"docs/src/**/{api-search,nav-toggle}.js\" docs/build/arcgis-rest-js -w", "lint": "tslint --project tsconfig.json", "lint:fix": "tslint --project tsconfig.json --fix", "precommit": "lint-staged", From a81852e9b1dbaeb43da30ae9701a6e3ace4494d6 Mon Sep 17 00:00:00 2001 From: Noah Mulfinger Date: Fri, 5 Oct 2018 11:55:57 -0700 Subject: [PATCH 2/2] Use generate helper to create search index --- docs/acetate.config.js | 25 ++++++++++++++----------- docs/src/js/index.js | 1 - 2 files changed, 14 insertions(+), 12 deletions(-) delete mode 100644 docs/src/js/index.js diff --git a/docs/acetate.config.js b/docs/acetate.config.js index 6c09b50e97..d08d10de18 100644 --- a/docs/acetate.config.js +++ b/docs/acetate.config.js @@ -17,14 +17,6 @@ module.exports = function(acetate) { } }); - acetate.load("js/index.js", { - basePath: "arcgis-rest-js", - metadata: { - layout: false, - prettyUrl: false - } - }); - acetate.metadata("**/*", { isDev: IS_DEV }); @@ -118,7 +110,7 @@ module.exports = function(acetate) { /** * Use Acetates generate helper to generate a page for each `declaration` - * and `package` in the typedoc.json. + * and `package` in the typedoc.json and generate the search index file */ acetate.generate((createPage, callback) => { fs.readFile( @@ -146,9 +138,18 @@ module.exports = function(acetate) { ); }); + const searchIndex = createPage.fromTemplateString( + "arcgis-rest-js/js/index.js", + `const ESRI_REST_API_REF_INDEX = ${JSON.stringify( + typedoc.quickSearchIndex + )}`, + path.join(acetate.sourceDir, "js", "index.js"), + { layout: false, prettyUrl: false } + ); + // once all the pages have been generated provide them to Acetate. Promise.all(declarationPages.concat(packagePages)).then(pages => { - callback(null, pages); + callback(null, pages.concat(searchIndex)); }); } ); @@ -206,7 +207,9 @@ module.exports = function(acetate) { // friendly script tag string // future entry point for adding SRI hash acetate.helper("scriptTag", function(context, package) { - return `<script src="https://unpkg.com/${package.name}@${package.version}/dist/umd/${package.name.replace("@esri/arcgis-rest-", "")}.umd.min.js"></script>`; + return `<script src="https://unpkg.com/${ + package.name + }@${package.version}/dist/umd/${package.name.replace("@esri/arcgis-rest-", "")}.umd.min.js"></script>`; }); acetate.helper("npmInstallCmd", function(context, package) { diff --git a/docs/src/js/index.js b/docs/src/js/index.js deleted file mode 100644 index 9b08a3c07d..0000000000 --- a/docs/src/js/index.js +++ /dev/null @@ -1 +0,0 @@ -const ESRI_REST_API_REF_INDEX = {{ data.typedoc.quickSearchIndex | dump | safe }};