https://api-extractor.com/assets/js/3dc585c7.3df6a244.js

1"use strict";(self.webpackChunkapi_extractor_com=self.webpackChunkapi_extractor_com||[]).push([[5801],{5552:(e,t,a)=>{a.d(t,{xA:()=>c,yg:()=>d});var n=a(829);function r(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function o(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter(function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable})),a.push.apply(a,n)}return a}function i(e){for(var t=1;t<arguments.length;t++){var a=null!=arguments[t]?arguments[t]:{};t%2?o(Object(a),!0).forEach(function(t){r(e,t,a[t])}):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(a)):o(Object(a)).forEach(function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(a,t))})}return e}function s(e,t){if(null==e)return{};var a,n,r=function(e,t){if(null==e)return{};var a,n,r={},o=Object.keys(e);for(n=0;n<o.length;n++)a=o[n],t.indexOf(a)>=0||(r[a]=e[a]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n<o.length;n++)a=o[n],t.indexOf(a)>=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var p=n.createContext({}),l=function(e){var t=n.useContext(p),a=t;return e&&(a="function"==typeof e?e(t):i(i({},t),e)),a},c=function(e){var t=l(e.components);return n.createElement(p.Provider,{value:t},e.children)},u="mdxType",g={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},m=n.forwardRef(function(e,t){var a=e.components,r=e.mdxType,o=e.originalType,p=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),u=l(a),m=r,d=u["".concat(p,".").concat(m)]||u[m]||g[m]||o;return a?n.createElement(d,i(i({ref:t},c),{},{components:a})):n.createElement(d,i({ref:t},c))});function d(e,t){var a=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var o=a.length,i=new Array(o);i[0]=m;var s={};for(var p in t)hasOwnProperty.call(t,p)&&(s[p]=t[p]);s.originalType=e,s[u]="string"==typeof e?e:r,i[1]=s;for(var l=2;l<o;l++)i[l]=a[l];return n.createElement.apply(null,i)}return n.createElement.apply(null,a)}m.displayName="MDXCreateElement"},6614:(e,t,a)=>{a.r(t),a.d(t,{assets:()=>c,contentTitle:()=>p,default:()=>d,frontMatter:()=>s,metadata:()=>l,toc:()=>u});var n=a(6443),r=a(8338),o=(a(829),a(5552)),i=["components"],s={title:"Generating API docs"},p=void 0,l={unversionedId:"pages/setup/generating_docs",id:"pages/setup/generating_docs",title:"Generating API docs",description:'_This article continues the tutorial from the "Invoking API Extractor" page.',source:"@site/docs/pages/setup/generating_docs.md",sourceDirName:"pages/setup",slug:"/pages/setup/generating_docs",permalink:"/pages/setup/generating_docs",draft:!1,editUrl:"https://github.com/microsoft/rushstack-websites/tree/main/websites/api-extractor.com/docs/pages/setup/generating_docs.md",tags:[],version:"current",frontMatter:{title:"Generating API docs"},sidebar:"docsSidebar",previous:{title:"Configuring a .d.ts rollup",permalink:"/pages/setup/configure_rollup"},next:{title:"Integrating a custom doc pipeline",permalink:"/pages/setup/custom_docs"}},c={},u=[{value:"Generating JSON files",id:"generating-json-files",level:2},{value:"Using api-documenter to generate Markdown",id:"using-api-documenter-to-generate-markdown",level:2},{value:"Using api-documenter with DocFX",id:"using-api-documenter-with-docfx",level:2}],g={toc:u},m="wrapper";function d(e){var t=e.components,a=(0,r.A)(e,i);return(0,o.yg)(m,(0,n.A)({},g,a,{components:t,mdxType:"MDXLayout"}),(0,o.yg)("head",null,(0,o.yg)("link",{rel:"canonical",href:"https://api-extractor.com/pages/pages/setup/generating_docs/"})),(0,o.yg)("p",null,(0,o.yg)("em",{parentName:"p"},'This article continues the tutorial from the "',(0,o.yg)("a",{parentName:"em",href:"/pages/setup/invoking"},"Invoking API Extractor"),"\" page.\nIt's recommended to start there.")),(0,o.yg)("h2",{id:"generating-json-files"},"Generating JSON files"),(0,o.yg)("p",null,'API Extractor writes your extracted API signature and doc comments into an intermediary JSON file called\nthe "doc model" file. To enable this output, you simply need to set ',(0,o.yg)("inlineCode",{parentName:"p"},"docModel.enabled")," to true in\nyour ",(0,o.yg)("strong",{parentName:"p"},"api-extractor.json")," config file."),(0,o.yg)("p",null,"The doc model file is written to ",(0,o.yg)("inlineCode",{parentName:"p"},'"<projectFolder>/temp/<unscopedPackageName>.api.json"')," by default,\nbut you can customize this using the ",(0,o.yg)("inlineCode",{parentName:"p"},"docModel.apiJsonFilePath")," setting."),(0,o.yg)("h2",{id:"using-api-documenter-to-generate-markdown"},"Using api-documenter to generate Markdown"),(0,o.yg)("p",null,"API Extractor includes a companion tool called ",(0,o.yg)("strong",{parentName:"p"},"api-documenter")," that you can use to generate a basic API reference\nwebsite. The Markdown output is fairly basic, since the ",(0,o.yg)("inlineCode",{parentName:"p"},"MarkdownDocumenter.ts")," source file was designed to be concise\nand understandable, while still functionally complete. That way it can serve as a starting point for people who want\nto implement their own adapter to process API Extractor's doc model using a custom pipeline (discussed later).\nEven so, Markdown output can be a realistic solution if your needs are not too fancy, and it is very easy to use."),(0,o.yg)("p",null,"As input, ",(0,o.yg)("strong",{parentName:"p"},"api-documenter")," accepts a folder containing doc model files, one for each package that you want\nto incorporate. This allows a collection of related projects to be built separately (perhaps in separate Git repos\nusing different toolchains). The documentation pipeline collects these JSON files, and then uses them to generate\na single website, complete with cross-package hyperlinks and an integrated navigation tree."),(0,o.yg)("p",null,"Here's a typical usage scenario:"),(0,o.yg)("ol",null,(0,o.yg)("li",{parentName:"ol"},(0,o.yg)("p",{parentName:"li"},"(Separately) Invoke API Extractor for each project that you want to document. This will produce one or more\n.api.json files.")),(0,o.yg)("li",{parentName:"ol"},(0,o.yg)("p",{parentName:"li"},"Copy your .api.json files into an input folder, for example:"),(0,o.yg)("ul",{parentName:"li"},(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("strong",{parentName:"li"}

1,"~/my-docs/input/")," ","\xa0","\xa0"," (.api.json inputs go here)"),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("strong",{parentName:"li"},"~/my-docs/markdown/")," ","\xa0","\xa0"," (.md output files will go here)"))),(0,o.yg)("li",{parentName:"ol"},(0,o.yg)("p",{parentName:"li"},"Install the ",(0,o.yg)("a",{parentName:"p",href:"https://www.npmjs.com/package/@microsoft/api-documenter"},"api-documenter tool")," in your global\nenvironment, using a shell command like this:"),(0,o.yg)("pre",{parentName:"li"},(0,o.yg)("code",{parentName:"pre",className:"language-shell"},"$ npm install -g @microsoft/api-documenter\n")),(0,o.yg)("p",{parentName:"li"},"Assuming your ",(0,o.yg)("inlineCode",{parentName:"p"},"PATH")," environment variable is set up correctly, now you should now be able to invoke\n",(0,o.yg)("inlineCode",{parentName:"p"},"api-documenter")," from your shell.")),(0,o.yg)("li",{parentName:"ol"},(0,o.yg)("p",{parentName:"li"},"Run the ",(0,o.yg)("strong",{parentName:"p"},"api-documenter")," tool like this:"),(0,o.yg)("pre",{parentName:"li"},(0,o.yg)("code",{parentName:"pre",className:"language-shell"},"$ cd ~/my-docs/\n$ api-documenter markdown\n")),(0,o.yg)("p",{parentName:"li"},"You can customize these folders using parameters such as ",(0,o.yg)("inlineCode",{parentName:"p"},"--input-folder")," and ",(0,o.yg)("inlineCode",{parentName:"p"},"--output-folder"),".\nSee ",(0,o.yg)("a",{parentName:"p",href:"/pages/commands/api-documenter_markdown"},"the command line reference")," for details."))),(0,o.yg)("p",null,"What do we do with these generated Markdown files? There are various options:"),(0,o.yg)("ul",null,(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("p",{parentName:"li"},(0,o.yg)("strong",{parentName:"p"},"GitHub"),": If you're using GitHub, you can simply commit them to your master branch in\na \"docs\" folder, and they will be rendered using GitHub's markdown previewer. Here's an example of how it looks:\n",(0,o.yg)("a",{parentName:"p",href:"https://github.com/microsoft/rushstack-websites/blob/main/websites/api.rushstack.io/docs/pages/node-core-library.md"},"node-core-library.md"))),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("p",{parentName:"li"},(0,o.yg)("strong",{parentName:"p"},"GitHub Pages"),": If you use ",(0,o.yg)("a",{parentName:"p",href:"https://guides.github.com/features/pages/"},"GitHub pages"),' to host a web site for\nyour project, your repo will probably have a "gh-pages" branch. You can add the Markdown files there,\nas seen here:'),(0,o.yg)("p",{parentName:"li"},"Example branch: ",(0,o.yg)("a",{parentName:"p",href:"https://github.com/microsoft/rushstack-websites/tree/main/websites/api.rushstack.io/docs/pages"},"https://github.com/microsoft/rushstack-websites/tree/main/websites/api.rushstack.io/docs/pages")),(0,o.yg)("p",{parentName:"li"},"Example website: ",(0,o.yg)("a",{parentName:"p",href:"https://api.rushstack.io/pages/"},"https://api.rushstack.io/pages/"))),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("p",{parentName:"li"},(0,o.yg)("strong",{parentName:"p"},"Docusaurus"),": These Markdown files can also be rendered using ",(0,o.yg)("a",{parentName:"p",href:"https://docusaurus.io/"},"Docusaurus"),", which\nproduces a React-based web site using Markdown inputs."),(0,o.yg)("p",{parentName:"li"},"Example branch: ",(0,o.yg)("a",{parentName:"p",href:"https://github.com/faastjs/faast.js/tree/master/docs/api"},"https://github.com/faastjs/faast.js/tree/master/docs/api")),(0,o.yg)("p",{parentName:"li"},"Example website: ",(0,o.yg)("a",{parentName:"p",href:"https://faastjs.org/docs/api/faastjs"},"https://faastjs.org/docs/api/faastjs")))),(0,o.yg)("h2",{id:"using-api-documenter-with-docfx"},"Using api-documenter with DocFX"),(0,o.yg)("p",null,'If Markdown output is the "go-kart" of documentation generation, then\n',(0,o.yg)("a",{parentName:"p",href:"https://dotnet.github.io/docfx/"},"DocFX"),' is the "space shuttle". It\'s a fairly complex but professional\nsystem with nearly every feature imaginable, since it was created to power\n',(0,o.yg)("a",{parentName:"p",href:"https://docs.microsoft.com"},"docs.microsoft.com"),". As far as API Extractor's involvement, the workflow is the same\nas above, except that the shell command is ",(0,o.yg)("inlineCode",{parentName:"p"},"api-documenter yaml")," instead of ",(0,o.yg)("inlineCode",{parentName:"p"},"api-documenter markdown"),".\nSetting up DocFX can be a little challenging (unless you work at Microsoft, in which case it's super easy! :-) )."),(0,o.yg)("p",null,"The sites that DocFX produces are very full-featured. Here's a couple API references that were generated\nusing ",(0,o.yg)("strong",{parentName:"p"},"api-documenter")," with DocFX:"),(0,o.yg)("ul",null,(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"https://docs.microsoft.com/en-us

1/javascript/api/excel?view=excel-js-preview"},"Add-ins platform")," for Microsoft Office"),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"https://esfx.js.org/esfx/index.html"},"API reference")," for the ",(0,o.yg)("a",{parentName:"li",href:"https://esfx.js.org/"},"@esfix")," project")),(0,o.yg)("p",null,"These are nice options. But suppose you have custom needs, and you're not afraid to write some code to get\nwhat you want..."))}d.isMDXComponent=!0}}]);