Giter VIP home page Giter VIP logo

api-docs's Introduction

api-docs

Generator for API documentation based on output from the Highcharts JSDoc plugin

Folders

templates/ - handlebars templates include/ - contents is copied over to the output

Usage

Shortcut:

When running the highcharts repo, run gulp jsdoc --watch. It will pull in this repo and start a local server with the docs.

Detailed:

npm install
sudo npm link

Then run hc-gen-api-docs <input.json> <outputpath/> in a termnial, or bin/gen.docs.js.

OPTIONS:
  --platform      Define which platform were building for. e.g 'Android', 'iOS', or 'JS' - default: 'JS'.
  --products      Define which products to build. - default: "highcharts,highstock,highmaps".
  --allVersions   Build all versions. - default: false.

A server is automagically started on port 9700 to serve up the docs. The server listens to changes on files in include and templates, and rebuilds the docs if there are any. This only works if the ouput folder is a folder - docs/ - in the project root.

This is to decrease turn-around time when working on design etc.

Generated files

Files are generated in a hierarchy as such:

  • product_name
    • version 1
    • version 2

The root product_name folder contains the documentation for the latest sources.

Each property with one or more child properties get its own HTML file.

In addition, JSON files for each property with children gets a slim JSON file in the nav/ folder, for use with the navigation tree.

Each folder also gets its own products.json, which contains the required information for implementing a version picker in the UI:

     {
      "activeProduct": "highcharts",
      "activeVersion": "current",
      "library": {
        "highcharts": {
          "current": "./",
          "1.2.4": "./../1.2.4/",
          "1.2.3": "./../1.2.3/"
        },
        "highstock": {
          "current": "./../highstock/",
          "1.2.4": "./../highstock/1.2.4/",
          "1.2.3": "./../highstock/1.2.3/"
        },
        "highmaps": {
          "current": "./../highmaps/"
        }
      }
    }

The version paths are relative to the current folder.

License

Please see the license file.

api-docs's People

Contributors

bre1470 avatar cvasseng avatar jon-a-nygaard avatar oysteinmoseng avatar torsteinhonsi avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Forkers

isabella232

api-docs's Issues

Feature request: add support for product blacklisting

Adding support for product blacklisting in the @products tag would make things less verbose in situations where e.g. an option is enabled for 3/4 products.

The syntax could be:

@products  -highmaps

In order to retain compatibility with other tools, this should be rewritten automatically during the parsing stage to the current whitelisting form.

Things are missing in plotOptions inheritance

  • plotOptions.series is the basics. This is correct.
  • plotOptions.line should inherit plotOptions.series, which seems to go wrong.
  • plotOptions.area should inherit plotOptions.line, which seems to be correct, but things are missing in the previous step.

Differences in properties between products are not respected

Example 1, the top level description for xAxis should be different between Highcharts an Highmaps: http://api.highcharts.com/highcharts/xAxis, http://api.highcharts.com/highmaps/xAxis.

Example 2, http://api.highcharts.com/highmaps/xAxis.allowDecimals has a different description in Highmaps.

Example 3, http://api.highcharts.com/highstock/title.text. Highstock has title.text to null by default, while it is Chart title in Highcharts.

While preparing a fix for this, we should print out a list of the corresponding properties that have different values (including different default value).


Edit: The safest approach, at least initially, would be to maintain completely separate doclets for the products in cases where any property differs. Later we can explore the possibility of allowing differences in specific properties, like @defaults, or @sample's that are filtered by product.

Loose doclets gives error

/**
 * Pelle politivil
 *
 * @sample highcharts/demo/treemap-large-dataset/ Treemap
 * 
 * @extends {plotOptions.treemap}
 * @product highcharts
 * @optionparent plotOptions.sunburst
 */
var sunburstOptions = {
	/**
	 * Pelle
	 * 
	 * @type {Boolean}
	 * @sample {highcharts} highcharts/plotoptions/treemap-interactbyleaf-false/ False
	 * @sample {highcharts} highcharts/plotoptions/treemap-interactbyleaf-true-and-allowdrilltonode/ InteractByLeaf and allowDrillToNode is true
	 * @since 6.0.0
	 * @product highcharts
	 * @apioption plotOptions.sunburst.interactByLeaf
	 */
};

Google Analytics on API

Marketing-department want Google Analytics on our API - in general and specific on JSFiddle-URL's.

Contact Linda for more detailed information.

They want it asap, as they want to start gathering data as soon as possible.

Error in generating API

It looks like I have some problems with jsdoc-api generator. Details:

$ gulp jsdoc --watch
[11:58:08] Using gulpfile ~/projects/projects/highcharts/gulpfile.js
[11:58:08] Starting ‘jsdoc’...
Watching file changes in JS files and templates
Starting API docs server http://localhost:9005
[11:58:11] Documented 24 files!
[11:58:11] Finished ‘jsdoc’ after 3.16 s
Created class-reference
[11:58:12] /Users/pawelfus/projects/projects/highcharts/tools/jsdoc/plugins/highcharts.jsdoc.js:168
s = comment.indexOf(‘@optionparent’);

TypeError: Cannot read property ‘indexOf’ of undefined
at Object.nodeVisitor [as visitNode] (/Users/pawelfus/projects/projects/highcharts/tools/jsdoc/plugins/highcharts.jsdoc.js:168:20)

In the highcharts.jsdoc.js file, this is responsible line:

comment = node.leadingComments[0].raw;

Changing to

comment = node.leadingComments[0].raw || ‘’;

generates api docs, however I’m not sure what exactly happens here. @christer ?

New lines inside code blocks are messing things up

In cases where a doclet is defined as such:

/**
* A custom class name, in addition to the default `highcharts-plot-
* line`, to apply to each individual line.
*/

there's an extra space in the output (highcharts-plot- line). There are also several cases of straight up newlines inside doclet descriptions, which leads to e.g. highcharts-plot-\nband.

Excluded props re-appear in children.

The inheritance is as follows

Line => Column => Histogram.

The connectNulls property is excluded in the Column series, which works correctly. The Histogram series inherits from column, but the connectNulls property (and others) appear there, which is not correct.

Menu layout doesn't reflect series types

The menu layout doesn't reflect the difference between nested objects and the series array where the type property dictates what options are available.

In the current API it is presented like this to highlight that type is an option:

skjermbilde 2017-06-16 kl 14 31 25

Default values should be filtered by product

Products are given in curly brackets:

@default {highcharts} true

Multiple products should be supported:

@default {highcharts|highstock} true

When left out, the default should apply to all products:

@default true

Multiple tags should be supported on each doclet:

@default {highcharts|highstock} true
@default {highmaps} false

Default values not always parsed

Strings are correctly parsed, while boolean false as well as numbers seems to not be parsed.

Case: drilldown.drillUpButton.position, where the default value for align is correctly parsed, but not x and y.

tree.json missing

There's the "View as JSON" link in the UI, but the tree.json file is not found in the output.

Missing from @extends

In extended options, existing properties are not overwritten.

For example, the default of plotOptions.scatter.findNearestPointBy should be xy, but the API says x.

Another example, plotOptions.column.cropThreshold should be 50 by default, and marker should be removed.

Properties that don't exist on the parent object are correctly handled.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.