3 |
6 |
14 | {{/obsoleteMessagesWithMoniker}}
15 |
16 |
--------------------------------------------------------------------------------
/.github/workflows/gh-page.yml:
--------------------------------------------------------------------------------
1 | name: gh-pages
2 | on:
3 | push:
4 | branches:
5 | - main
6 |
7 | jobs:
8 | gh-pages:
9 | runs-on: ubuntu-latest
10 | steps:
11 | - uses: actions/checkout@v2
12 | with:
13 | fetch-depth: 0
14 | submodules: true
15 | - uses: actions/setup-dotnet@v1
16 | with:
17 | dotnet-version: '6.0.x'
18 |
19 | - run: yarn
20 | - run: yarn build
21 | env:
22 | DOCFX__SECRETS__GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
23 |
24 | - uses: peaceiris/actions-gh-pages@v3
25 | with:
26 | github_token: ${{ secrets.GITHUB_TOKEN }}
27 | publish_dir: samples/_site
28 |
--------------------------------------------------------------------------------
/samples/tutorial/incrementalbuild/toc.yml:
--------------------------------------------------------------------------------
1 | - name: Introduction to DocFX incremental build
2 | href: intro_incremental_build.md
3 | - name: Customize a processor to support incremental build
4 | href: customize_a_processor_to_support_incremental.md
5 | - name: 'Advanced: Report Dependency'
6 | href: advanced_report_dependency.md
7 | - name: 'Advanced: Cache File Structure'
8 | href: advanced_cache_file_structure.md
9 | - name: Incremental post processing
10 | items:
11 | - name: Introduction to incremental post processing
12 | href: intro_incremental_post_processing.md
13 | - name: Customize a post processor to be incremental
14 | href: customize_a_post_processor_to_be_incremental.md
--------------------------------------------------------------------------------
/ContentTemplate/partials/dotnet/returns.tmpl.partial:
--------------------------------------------------------------------------------
1 | {{#returnsWithMoniker}}
2 | {{#returnLabel}}
3 | {{{__global.caution}}}
7 | {{^value}}
8 | {{__global.deprecated}}
9 | {{/value}} 10 | {{#value}} 11 | {{{.}}} 12 | {{/value}} 13 |{{returnLabel}}
4 | {{/returnLabel}} 5 | 6 | {{^returnLabel}} 7 |{{__global.returnValue}}
8 | {{/returnLabel}} 9 | 10 | {{#type}} 11 |-
12 |
- 13 | {{^valuePerLanguage}}{{{value}}}{{/valuePerLanguage}} 14 | {{#valuePerLanguage}}{{{value}}}{{/valuePerLanguage}} 15 | 16 |
{{__global.parameters}}
3 | {{/parameters.0}} 4 | {{#parameters}} 5 |
6 |
18 | {{/parameters}}
--------------------------------------------------------------------------------
/ContentTemplate/partials/dotnet/typeParameters.tmpl.partial:
--------------------------------------------------------------------------------
1 | {{#typeParameters.0}}
2 | -
7 |
- 8 | {{^namesWithMoniker}}{{name}}{{/namesWithMoniker}} 9 | {{#namesWithMoniker}}{{value}}{{/namesWithMoniker}} 10 | 11 |
- 12 | {{^typePerLanguage}}{{{type}}}{{/typePerLanguage}} 13 | {{#typePerLanguage}}{{{value}}}{{/typePerLanguage}} 14 | 15 |
{{__global.typeParameters}}
3 | {{/typeParameters.0}} 4 | {{#typeParameters}} 5 |
6 |
24 | {{/typeParameters}}
--------------------------------------------------------------------------------
/ContentTemplate/Conceptual.mta.json.js:
--------------------------------------------------------------------------------
1 | // Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
2 |
3 | var chromeCommon = require('./chrome.common.js')
4 |
5 | exports.transform = function (model) {
6 | model.toc_rel = model._tocRel;
7 | model.layout = model.layout || "Conceptual";
8 | delete model.conceptual;
9 |
10 | var contrib = model._op_gitContributorInformation;
11 | if (contrib && contrib.author) {
12 | contrib.contributors = contrib.contributors || [];
13 | contrib.contributors.unshift(contrib.author);
14 | }
15 |
16 | chromeCommon.makeGitHubRepoLink(model);
17 |
18 | return {
19 | content: JSON.stringify(model)
20 | }
21 | }
--------------------------------------------------------------------------------
/ContentTemplate/schemas/Menu.schema.json:
--------------------------------------------------------------------------------
1 | {
2 | "$schema": "http://json-schema.org/draft-07/schema##",
3 | "description": "The schema for the main menu bar",
4 | "type": "object",
5 | "required": ["items"],
6 | "renderType": "Component",
7 | "properties": {
8 | "items": {
9 | "type": "array",
10 | "minItems": 1,
11 | "items": {
12 | "type": "object",
13 | "properties": {
14 | "name": {
15 | "type": "string"
16 | },
17 | "href": {
18 | "type": "string",
19 | "contentType": "href"
20 | }
21 | }
22 | }
23 | }
24 | }
25 | }
26 |
--------------------------------------------------------------------------------
/ContentTemplate/partials/dotnet/additionalRequirements.tmpl.partial:
--------------------------------------------------------------------------------
1 | {{#displayAdditionalRequirements}}
2 | -
7 |
- {{name}} 8 |
- 9 | {{#constraints}} 10 | {{parameterAttribute}} {{baseTypeName}} 11 | {{/constraints}} 12 | 13 |
{{__global.additionalFeaturesAndRequirements}}
3 || {{__global.softwareDevelopmentKit}} | 7 |
8 |
9 | {{name}}
10 |
11 | |
12 |
| {{__global.minimumSupportedOS}} | 18 |
19 |
20 | {{name}} ({{minVersion}})
21 |
22 | |
23 |
{{__global.internalUseOnly}}
10 | {{/isInternalOnly}} 11 | {{#obsoleteMessagesWithMoniker}} 12 |
13 | {{__global.obsolete}}
14 |
15 | {{/obsoleteMessagesWithMoniker}}
16 | {{{summary}}}
17 |
3 |
18 | {{/summary}}
19 | {{^summary}}
20 | {{#crossInheritdocsUid}}
21 |
4 | {{#editLink}}
5 |
17 |
6 | {{__global.edit}}
7 |
8 | {{/editLink}}
9 | {{{summary}}}
10 | {{#isFlags}}
11 | {{{__global.flagsAttributeDisclaimer}}}
12 | {{/isFlags}} 13 | {{#isInternalOnly}} 14 |{{__global.internalUseOnly}}
15 | {{/isInternalOnly}} 16 |
22 |
26 | {{/crossInheritdocsUid}}
27 | {{/summary}}
--------------------------------------------------------------------------------
/_includes/header.liquid:
--------------------------------------------------------------------------------
1 |
22 |
--------------------------------------------------------------------------------
/ContentTemplate/partials/dotnet/inheritance.tmpl.partial:
--------------------------------------------------------------------------------
1 | {{#hasInheritancesWithMonikers}}
2 | {{#inheritancesWithMoniker}}
3 |
23 |
25 | -
4 |
- {{__global.inheritance}} 5 |
-
6 | 7 | {{^hasPerLanguageInheritancesWithMonikers}} 8 | {{#values}} 9 |19 |{{{ . }}}10 | {{/values}} 11 | {{/hasPerLanguageInheritancesWithMonikers}} 12 | {{#hasPerLanguageInheritancesWithMonikers}} 13 | {{#valuesPerLanguage}} 14 | {{{value}}} 15 | {{/valuesPerLanguage}} 16 | {{/hasPerLanguageInheritancesWithMonikers}} 17 | {{#rootName}} {{{rootName}}} {{/rootName}} 18 |
20 |
-
3 |
- {{__global.implements}}
-
4 | 5 | {{#implementsWithMoniker}} 6 | {{^valuePerLanguage}} 7 | 8 | {{{ value }}} 9 | 10 | {{/valuePerLanguage}} 11 | {{#valuePerLanguage}} 12 | 13 | {{{ value }}} 14 | 15 | {{/valuePerLanguage}} 16 | {{/implementsWithMoniker}} 17 |18 |
19 |
-
3 |
- {{__global.attributes}} 4 |
-
5 | 6 | {{#attributesWithMoniker}} 7 | {{^valuePerLanguage}} 8 | 9 |18 |
10 | {{/valuePerLanguage}} 11 | {{#valuePerLanguage}} 12 | 13 | 14 | 15 | {{/valuePerLanguage}} 16 | {{/attributesWithMoniker}} 17 |
19 |
{{{title}}}
2 | 3 | {{>partials/reference-metadata}} 4 | 5 | 6 | {{>partials/dotnet/typeHeader}} 7 | {{>partials/dotnet/monikerBoilerplate}} 8 | {{>partials/dotnet/deprecated}} 9 | {{>partials/dotnet/summary}} 10 | {{>partials/docOutline}} 11 | 12 | {{>partials/dotnet/syntax}} 13 | {{>partials/dotnet/inheritance}} 14 | {{>partials/dotnet/attribute}} 15 | {{>partials/dotnet/uwpProperties}} 16 | {{>partials/dotnet/additionalRequirements}} 17 | 18 | {{#fieldsInfo}} 19 |{{__global.fieldsInSubtitle}}
20 || 26 | {{#name}} 27 | {{name}} 28 | {{/name}} 29 | | 30 |{{literalValue}} | 31 |{{{summary}}} | 32 |
2 |
3 | {{>partials/dotnet/deprecated}}
4 | {{>partials/dotnet/clsCompliantAlternative}}
5 | {{>partials/dotnet/summary}}
6 | {{>partials/dotnet/syntax}}
7 | {{>partials/dotnet/typeParameters}}
8 | {{>partials/dotnet/parameters}}
9 | {{>partials/dotnet/returns}}
10 | {{>partials/dotnet/memberCommon}}
11 | {{>partials/dotnet/uwpProperties}}
12 | {{>partials/dotnet/additionalRequirements}}
13 |
14 | {{#examples}}
15 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2020 docfx
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/src/styles/nav.scss:
--------------------------------------------------------------------------------
1 | // Copyright (c) Microsoft. All rights reserved.
2 | // Licensed under the MIT license. See LICENSE file in the project root for full license information.
3 |
4 | header {
5 | .navbar {
6 | background-color: var(--navbar-bg-color);
7 | }
8 |
9 | @media print {
10 | display: none;
11 | }
12 | }
13 |
14 | .in-this-article{
15 | font-size: 14px;
16 | padding-top: .5em;
17 |
18 | h5 {
19 | font-weight: bold;
20 | text-transform: uppercase;
21 | font-size: inherit;
22 | }
23 | .nav {
24 | display: block;
25 | padding-left: 0;
26 |
27 | a {
28 | padding: 2px 2px 2px 6px;
29 | border-left: 3px solid transparent;
30 | }
31 | a.active {
32 | border-left: 3px solid $primary;
33 | }
34 | a:hover {
35 | text-decoration: underline;
36 | }
37 | }
38 | }
39 |
40 | footer {
41 | background-color: #f8f8f8;
42 | padding: 2rem 0;
43 |
44 | .github-star-button {
45 | display: inline-block;
46 | position: relative;
47 | top: 5px;
48 | margin: 0 10px;
49 | }
50 |
51 | @media print {
52 | display: none;
53 | }
54 | }
55 |
--------------------------------------------------------------------------------
/ContentTemplate/Home.html.primary.tmpl:
--------------------------------------------------------------------------------
1 | {{#hero}}
2 | {{__global.examples}}
16 | {{{.}}} 17 | {{/examples}} 18 | 19 | {{#remarks}} 20 |{{__global.remarks}}
21 | {{{.}}} 22 | {{/remarks}} 23 | 24 | {{>partials/dotnet/additionalNotesWithBigHeader}} 25 | 26 | {{#hasPermissions}} 27 |{{__global.security}}
28 | {{>partials/dotnet/security}} 29 | {{/hasPermissions}} 30 | 31 | {{>partials/dotnet/moniker}} 32 | 33 | {{#threadSafety}} 34 |{{__global.threadSafety}}
35 | {{{threadSafety}}} 36 | {{/threadSafety}} 37 | 38 | {{#seeAlso}} 39 |{{__global.seeAlso}}
40 | {{{ . }}} 41 | {{/seeAlso}} 42 | 43 |
3 |
17 |
18 | {{/hero}}
19 |
20 | {{#quickstart}}
21 |
22 |
23 |
28 |
29 | {{/quickstart}}
30 |
31 | {{#highlights.0}}
32 | {{title}}
24 |
25 | {{{content}}}
26 |
27 |
33 |
44 | {{/highlights.0}}
45 |
--------------------------------------------------------------------------------
/ContentTemplate/partials/dotnet/typeHeader.tmpl.partial:
--------------------------------------------------------------------------------
1 |
34 | {{/highlights.0}}
35 | {{#highlights}}
36 |
37 |
40 | {{/highlights}}
41 | {{#highlights.0}}
42 |
43 | {{title}}
38 |{{{content}}}
39 | {{__global.definition}}
2 | 3 | -------------------------------------------------------------------------------- /src/scripts/utility.ts: -------------------------------------------------------------------------------- 1 | // Copyright (c) Microsoft. All rights reserved. 2 | // Licensed under the MIT license. See LICENSE file in the project root for full license information. 3 | 4 | export function meta(name: string): string { 5 | return (document.querySelector(`meta[name="${name}"]`) as HTMLMetaElement)?.content 6 | } 7 | 8 | export function isVisible(element: Element): boolean { 9 | return (element as HTMLElement).offsetParent != null 10 | } 11 | 12 | export function getAbsolutePath(href: string): string { 13 | if (!href) { 14 | return 15 | } 16 | const a = document.createElement('a') 17 | a.href = href 18 | return a.host + a.pathname; 19 | } 20 | 21 | export function isRelativePath(href: string): boolean { 22 | if (href === undefined || href === '' || href[0] === '/') { 23 | return false; 24 | } 25 | return !isAbsolutePath(href); 26 | } 27 | 28 | export function isAbsolutePath(href: string): boolean { 29 | return (/^(?:[a-z]+:)?\/\//i).test(href); 30 | } 31 | 32 | export function getDirectory(href: string): string { 33 | if (!href) return '.'; 34 | var index = href.lastIndexOf('/'); 35 | return index < 0 ? '.' : href.slice(0, index); 36 | } 37 | -------------------------------------------------------------------------------- /ContentTemplate/NetDelegate.html.primary.tmpl: -------------------------------------------------------------------------------- 1 |{{{title}}}
2 | 3 | {{>partials/reference-metadata}} 4 | 5 | {{>partials/dotnet/typeHeader}} 6 | {{>partials/dotnet/monikerBoilerplate}} 7 | {{>partials/dotnet/deprecated}} 8 | {{>partials/dotnet/clsCompliantAlternative}} 9 | {{>partials/dotnet/summary}} 10 | {{>partials/docOutline}} 11 | 12 | {{>partials/dotnet/syntax}} 13 | 14 | {{>partials/dotnet/typeParameters}} 15 | {{>partials/dotnet/parameters}} 16 | {{>partials/dotnet/returns}} 17 | {{>partials/dotnet/inheritance}} 18 | {{>partials/dotnet/attribute}} 19 | {{>partials/dotnet/uwpProperties}} 20 | {{>partials/dotnet/additionalRequirements}} 21 | {{>partials/dotnet/typeContent}} 22 | 23 | {{#extensionMethodsInfo}} 24 |{{__global.extensionMethodsInSubtitle}}
25 |{{__global.win10Requirements}}
3 || {{__global.win10_deviceFamily}} | 8 |
9 |
10 | {{#deviceFamilies}}
11 | {{name}} ({{introducedInVersion}})
14 | 12 | {{/deviceFamilies}} 13 | |
15 |
| API contract |
21 |
22 | {{#apiContracts}}
23 | {{name}} ({{introducedInVersion}})
26 | 24 | {{/apiContracts}} 25 | |
27 |
| {{__global.win10_appCapabilities}} | 34 |
35 |
36 | {{#capabilities}}
37 | {{.}}
38 | {{/capabilities}}
39 |
40 | |
41 |
-
3 |
- {{__global.derived}} 4 |
-
5 | {{#derivedClassesWithMoniker}}
6 | 7 | 8 | {{#value}} 9 |13 | {{/derivedClassesWithMoniker}} 14 | {{#hiddenDerivedClassesWithMoniker.0}} 15 | {{#hiddenDerivedClassesWithMoniker}} 16 |
10 | {{/value}} 11 | 12 | 17 | 18 | {{#value}} 19 |23 | {{/hiddenDerivedClassesWithMoniker}} 24 | 25 | {{/hiddenDerivedClassesWithMoniker.0}} 26 |20 | {{/value}} 21 | 22 |
27 |
2 |
3 |
--------------------------------------------------------------------------------
/ContentTemplate/NetMember.html.primary.tmpl:
--------------------------------------------------------------------------------
1 | {{^isOverload}}
2 | {{#members.0}}
3 |
4 | {{/members.0}}
5 | {{/isOverload}}
6 |
7 |
4 |
8 |
9 | 5 | {{name}} 6 |
7 |
10 | {{>partials/dotnet/deprecated}}
11 | {{>partials/dotnet/clsCompliantAlternative}}
12 | {{>partials/dotnet/summary}}
13 | {{>partials/dotnet/syntax}}
14 | {{>partials/dotnet/typeParameters}}
15 | {{>partials/dotnet/parameters}}
16 | {{>partials/dotnet/returns}}
17 | {{>partials/dotnet/memberCommon}}
18 | {{>partials/dotnet/uwpProperties}}
19 | {{>partials/dotnet/additionalRequirements}}
20 |
21 | {{#examples}}
22 |
49 |
50 | {{__global.examples}}
23 | {{{.}}} 24 | {{/examples}} 25 | 26 | {{#remarks}} 27 |{{__global.remarks}}
28 | {{{.}}} 29 | {{/remarks}} 30 | 31 | {{>partials/dotnet/additionalNotes}} 32 | 33 | {{#hasPermissions}} 34 |{{__global.security}}
35 | {{>partials/dotnet/security}} 36 | {{/hasPermissions}} 37 | 38 | {{#threadSafety}} 39 |{{__global.threadSafety}}
40 | {{{threadSafety}}} 41 | {{/threadSafety}} 42 | 43 | {{#seeAlso}} 44 |{{__global.seeAlso}}
45 | {{{ . }}} 46 | {{/seeAlso}} 47 | {{>partials/dotnet/monikerOverloadMember}} 48 |{{{title}}}
8 | 9 | {{>partials/reference-metadata}} 10 | 11 | {{>partials/dotnet/typeHeader}} 12 | {{>partials/dotnet/monikerBoilerplate}} 13 | 14 | {{#isOverload}} 15 | {{>partials/dotnet/summary}} 16 | {{/isOverload}} 17 | 18 | {{>partials/docOutline}} 19 | 20 | {{#isOverload}} 21 |{{__global.overloads}}
22 | 23 ||
29 | |
31 |
32 | |
34 |
{{__global.threadSafety}}
54 | {{{customizedContent}}} 55 | {{/threadSafety}} 56 | -------------------------------------------------------------------------------- /samples/spec/sdp_design_spec.md: -------------------------------------------------------------------------------- 1 | Schema-driven Document Processor(SDP) Design Spec 2 | ==================================== 3 | 4 | ## 1. Overview 5 | DocFX supports different [document processors](../tutorial/howto_build_your_own_type_of_documentation_with_custom_plug-in.md) to handle different kinds of input. With a new data model introduced in, a new document processor is required to support that model, even most of the code logic is the same for these processors. With this situation considered, a Schema-driven Document Processor (abbreviated to *SDP* below) is introduced to simplify the process. Togethor with a well defined [DocFX Document Schema](docfx_document_schema.md), SDP is able to *validate* and *process* a new data model with no extra effort needed. 6 | 7 | ## 2. Workflow 8 | The workflow for SDP is illustrated below. In general, the schema file, with suggested naming convention, has `documentType` in its name, as `{documentType}`.schema.json (When `title` is defined in the schema file, `title` is considered as the `documentType` for this schema). `docfx` loads the schema files from `schemas` subfolder in `template` folder, and creates processors for these schema files with per schema file per processor. With data models are processed, `docfx` applies templates for that `documentType` to these data model, as details illustrated in [Template Introduction](../tutorial/intro_template.md#naming-rule-for-a-renderer-file) and generates output documentation. 9 | 10 |  11 | -------------------------------------------------------------------------------- /src/styles/home.scss: -------------------------------------------------------------------------------- 1 | // Copyright (c) Microsoft. All rights reserved. 2 | // Licensed under the MIT license. See LICENSE file in the project root for full license information. 3 | 4 | .layout-home { 5 | padding: 0; 6 | 7 | .hero { 8 | background-color: rgb(248, 248, 248); 9 | 10 | .hero-content { 11 | display: flex; 12 | flex-direction: column; 13 | align-items: center; 14 | padding: 5em 0; 15 | gap: 1em; 16 | 17 | h1 { 18 | font-size: calc(1.525rem + 3.3vw); 19 | font-weight: 600; 20 | } 21 | 22 | .lead { 23 | font-weight: 400; 24 | font-size: calc(1.275rem + .3vw); 25 | } 26 | 27 | .actions { 28 | display: flex; 29 | gap: 1em; 30 | 31 | .btn { 32 | font-weight: 600; 33 | @include button-size(.75em, 1.5em, 1.25em, .3em); 34 | } 35 | } 36 | } 37 | } 38 | 39 | .quickstart { 40 | &:nth-child(odd) { 41 | background-color: #f8f8f8; 42 | } 43 | section { 44 | padding: 4em 0; 45 | margin: 0; 46 | } 47 | } 48 | 49 | .highlights { 50 | display: flex; 51 | gap: 1em 3em; 52 | margin: 4em 0; 53 | 54 | @include media-breakpoint-down(md) { 55 | flex-direction: column; 56 | } 57 | 58 | section { 59 | flex-grow: 1; 60 | flex-basis: 0; 61 | h2 { 62 | font-size: 20px; 63 | } 64 | 65 | .content { 66 | font-size: 16px; 67 | } 68 | } 69 | } 70 | } 71 | -------------------------------------------------------------------------------- /ContentTemplate/NetNamespace.html.primary.js: -------------------------------------------------------------------------------- 1 | var contentCommon = require('./content.common.js'); 2 | var common = require('./common.js'); 3 | var dotnet = require('./partials/dotnet/transform.js'); 4 | 5 | exports.transform = function (model) { 6 | model._op_templateFilename = 'NetNamespace'; 7 | dotnet.updateTitle(model, true, model.__global.namespace); 8 | createChildId(model); 9 | 10 | dotnet.updateEditButton(model); 11 | 12 | return model; 13 | }; 14 | 15 | function createChildId(model) { 16 | if (model.classes) { 17 | model.classes = model.classes.map(mapUidToObject); 18 | model.classesInfo = dotnet.getTypeChildrenInfo(model, model.classes); 19 | } 20 | 21 | if (model.structs) { 22 | model.structs = model.structs.map(mapUidToObject); 23 | model.structsInfo = dotnet.getTypeChildrenInfo(model, model.structs); 24 | } 25 | 26 | if (model.interfaces) { 27 | model.interfaces = model.interfaces.map(mapUidToObject); 28 | model.interfacesInfo = dotnet.getTypeChildrenInfo(model, model.interfaces); 29 | } 30 | 31 | if (model.enums) { 32 | model.enums = model.enums.map(mapUidToObject); 33 | model.enumsInfo = dotnet.getTypeChildrenInfo(model, model.enums); 34 | } 35 | 36 | if (model.delegates) { 37 | model.delegates = model.delegates.map(mapUidToObject); 38 | model.delegatesInfo = dotnet.getTypeChildrenInfo(model, model.delegates); 39 | } 40 | } 41 | 42 | function mapUidToObject(item) { 43 | return { 44 | uid: item.uid, 45 | id: common.getHtmlId(item.uid), 46 | monikers: item.monikers 47 | }; 48 | } 49 | -------------------------------------------------------------------------------- /ContentTemplate/chrome.common.js: -------------------------------------------------------------------------------- 1 | var shared = require('./shared.js'); 2 | 3 | function preProcessSDPMetadata(model) { 4 | var prop = null, 5 | propName = null, 6 | propNameValue = null; 7 | 8 | if (model.metadata) { 9 | for (prop in model.metadata) { 10 | propName = prop.toString(); 11 | if (shared.isString(propName)) { 12 | propNameValue = model.metadata[propName]; 13 | if (propNameValue !== undefined && propNameValue !== null) { 14 | model[propName] = propNameValue; 15 | } 16 | } 17 | } 18 | model.metadata = undefined; 19 | } 20 | 21 | makeGitHubRepoLink(model); 22 | } 23 | 24 | function makeGitHubRepoLink(model) { 25 | if (model.original_content_git_url) { 26 | var match = model.original_content_git_url.match(/github.com\/(.*?)\/(.*?)\//) 27 | if (match && match[1] && match[2]) { 28 | model._githubOwner = match[1] 29 | model._githubName = match[2] 30 | } 31 | } 32 | } 33 | 34 | exports.makeGitHubRepoLink = makeGitHubRepoLink; 35 | exports.makeCanonicalUrl = () => { }; 36 | exports.makeDescription = () => { }; 37 | exports.makeTitle = () => { }; 38 | exports.replaceXrefTags = () => { }; 39 | exports.preProcessSDPMetadata = preProcessSDPMetadata; 40 | exports.processMetadata = () => { }; 41 | exports.processCommunityContributionMetadata = () => { }; 42 | exports.buildEditLink = shared.buildEditLink; 43 | exports.createHtmlId = shared.createHtmlId; 44 | exports.isArray = shared.isArray; 45 | exports.isBool = shared.isBool; 46 | exports.isObject = shared.isObject; 47 | exports.isString = shared.isString; 48 | -------------------------------------------------------------------------------- /ContentTemplate/partials/dotnet/memberCommon.tmpl.partial: -------------------------------------------------------------------------------- 1 | {{#hasImplements}} 2 |{{__global.implements}}
3 |
4 |
10 | {{/hasImplements}}
11 | {{#hasImplementsWithMoniker}}
12 |
5 | {{#implements}}
6 | {{{.}}}
7 | {{/implements}}
8 |
9 | {{__global.implements}}
13 |
14 |
29 | {{/hasImplementsWithMoniker}}
30 |
31 | {{>partials/dotnet/attribute}}
32 |
33 | {{#hasExceptions}}
34 |
15 | {{#implementsWithMoniker}}
16 | {{^valuePerLanguage}}
17 |
18 | {{{value}}}
19 |
20 | {{/valuePerLanguage}}
21 | {{#valuePerLanguage}}
22 |
23 | {{{value}}}
24 |
25 | {{/valuePerLanguage}}
26 | {{/implementsWithMoniker}}
27 |
28 | {{__global.exceptions}}
35 | {{#exceptions}} 36 |
37 |
42 | {{/exceptions}}
43 | {{/hasExceptions}}
--------------------------------------------------------------------------------
/samples/tutorial/universalreference/intro_multiple_langs_support.md:
--------------------------------------------------------------------------------
1 | # Introduction to Multiple Languages Support
2 |
3 | ## 1. Introduction
4 |
5 | DocFX supports generating API documentation for C# and VB natively. However, it's not limited to these. DocFX is designed to support any language. When generating documents for a language, two steps are required: generating metadata and building documents from the metadata.
6 |
7 | ## 2. Workflow
8 |
9 | ### 2.1 Generate Metadata
10 |
11 | As different programming language has different tool written with different language to generate API documentation, this step is not included in DocFX core. We call the tool used as **Metadata Tool**.
12 |
13 | As [UniversalReferenceDocumentProcessor](https://github.com/dotnet/docfx/tree/dev/src/Microsoft.DocAsCode.Build.UniversalReference) is used to process these metadata files, the metadata tool should generate files according the processor's input schema. The files should:
14 | 1. be in YAML format and end with `.yml` or `.yaml`
15 | 2. have YamlMime `### YamlMime:UniversalReference` as the first line
16 | 3. conform to the [data model defined for UniversalReference](https://github.com/dotnet/docfx/tree/dev/src/Microsoft.DocAsCode.DataContracts.UniversalReference)
17 |
18 | Usually, a TOC should be generated along with YAML files for easy navigation among files.
19 |
20 | ### 2.2 Build Document
21 |
22 | The YAML files generated are used as input to DocFX. DocFX will build these YAML files into HTML pages.
23 |
24 | ## 3. Supported Languages
25 | * [JavaScript](gen_doc_for_js.md)
26 | * TypeScript (coming soon ...)
27 | * Python (coming soon ...)
28 |
--------------------------------------------------------------------------------
/src/scripts/highlight.ts:
--------------------------------------------------------------------------------
1 | // Copyright (c) Microsoft. All rights reserved.
2 | // Licensed under the MIT license. See LICENSE file in the project root for full license information.
3 |
4 | import hljs from 'highlight.js';
5 |
6 | export function highlight() {
7 | document.querySelectorAll('pre code').forEach(block => {
8 | hljs.highlightElement(block as HTMLElement)
9 | })
10 |
11 | document.querySelectorAll('pre code[highlight-lines]').forEach(block => {
12 | if (block.innerHTML === "") return
13 | var lines = block.innerHTML.split('\n')
14 |
15 | var queryString = block.getAttribute('highlight-lines')
16 | if (!queryString) return
17 |
18 | var ranges = queryString.split(',')
19 | for (var j = 0, range; range = ranges[j++];) {
20 | var found = range.match(/^(\d+)\-(\d+)?$/)
21 | if (found) {
22 | // consider region as `{startlinenumber}-{endlinenumber}`, in which {endlinenumber} is optional
23 | var start = +found[1]
24 | var end = +found[2]
25 | if (isNaN(end) || end > lines.length) {
26 | end = lines.length
27 | }
28 | } else {
29 | // consider region as a sigine line number
30 | if (isNaN(range)) continue
31 | var start = +range
32 | var end = start
33 | }
34 | if (start <= 0 || end <= 0 || start > end || start > lines.length) {
35 | // skip current region if invalid
36 | continue;
37 | }
38 | lines[start - 1] = '' + lines[start - 1]
39 | lines[end - 1] = lines[end - 1] + ''
40 | }
41 |
42 | block.innerHTML = lines.join('\n')
43 | })
44 | }
--------------------------------------------------------------------------------
/samples/codesnippet/Rtf/RtfBuildStep.cs:
--------------------------------------------------------------------------------
1 | // Copyright (c) Microsoft. All rights reserved.
2 | // Licensed under the MIT license. See LICENSE file in the project root for full license information.
3 |
4 | namespace RtfDocumentProcessors
5 | {
6 | using System;
7 | using System.Collections.Generic;
8 | using System.Collections.Immutable;
9 | using System.Composition;
10 | using System.Threading.Tasks;
11 | using System.Threading.Tasks.Schedulers;
12 |
13 | using MarkupConverter;
14 | using Microsoft.DocAsCode.Plugins;
15 |
16 | [Export(nameof(RtfDocumentProcessor), typeof(IDocumentBuildStep))]
17 | public class RtfBuildStep : IDocumentBuildStep
18 | {
19 | #region Build
20 | private readonly TaskFactory _taskFactory = new TaskFactory(new StaTaskScheduler(1));
21 |
22 | public void Build(FileModel model, IHostService host)
23 | {
24 | string content = (string)((Dictionary
38 | {{{type}}}
39 |
40 | {{{description}}}
41 | -
2 |
- 3 | 4 | 5 | {%- if page.wordCount < 400 -%} 6 | {%- capture minToRead %}2{% endcapture -%} 7 | {%- else -%} 8 | {%- capture minToRead %}{{ page.wordCount | divided_by: 200 | round }}{% endcapture -%} 9 | {%- endif -%} 10 |
- {{ minToRead}} minutes to read 11 | {%- if page._op_gitContributorInformation.contributors and page._op_gitContributorInformation.contributors.size > 0 -%} 12 | {%- assign contributorMax = 5 -%} 13 | {%- assign contributorSize = page._op_gitContributorInformation.contributors.size -%} 14 | {%- if contributorSize <= contributorMax -%} 15 | {%- assign contributorCount = contributorSize | minus: 1 -%} 16 | {%- else -%} 17 | {%- assign contributorCount = contributorMax | minus: 1 -%} 18 | {%- endif -%} 19 | {%- if contributorSize == 1 -%} 20 | {%- capture contributor %}{%- loc contributor -%}{% endcapture -%} 21 | {%- else -%} 22 | {%- capture contributor %}{%- loc contributors -%}{% endcapture -%} 23 | {%- endif -%} 24 |
-
25 |
-
26 | {%- for i in (0..contributorCount) -%}
27 | {%- assign contributor = page._op_gitContributorInformation.contributors[i] -%}
28 | {%- if contributor.profile_url and contributor.profile_url.size > 0 -%}
29 |
-
30 |
31 |
32 |
33 |
34 | {%- endif -%}
35 | {%- endfor -%}
36 |
39 | {%- endif -%}
40 | -
30 |
31 |
{{{title}}}
2 | 3 | {{>partials/reference-metadata}} 4 | 5 | {{>partials/dotnet/monikerBoilerplate}} 6 | {{>partials/dotnet/summary}} 7 | {{>partials/docOutline}} 8 | 9 | {{#classesInfo}} 10 |14 | {{__global.classesInSubtitle}} 15 |
16 |28 | {{__global.structsInSubtitle}} 29 |
30 |42 | {{__global.interfacesInSubtitle}} 43 |
44 |56 | {{__global.enumsInSubtitle}} 57 |
58 |70 | {{__global.delegatesInSubtitle}} 71 |
72 |In this Article
) 76 | inThisArticle.appendChild( 77 | 84 | ) 85 | } 86 | -------------------------------------------------------------------------------- /samples/spec/docfx_incremental.md: -------------------------------------------------------------------------------- 1 | Doc-as-code: DocFx.exe Incremental Build Specification 2 | ========================================== 3 | 4 | This documentation describes the implementation of incrementally extracting metadata from source. Currently we are using *Roslyn* to compile and analyse source code on the fly. When input sources are large, it may take minutes to load and process the files. To speed up the extraction, previous extracted details are saved to cache for further reference. 5 | 6 | There are two level caches in current implementation. First one is called *Application* Level cache, and the other one is *Project* level cache. 7 | 8 | *Application* level cache is saved in file `%LocalAppData%/xdoc/cache`. 9 | 10 | For *Project* level cache, 11 | 12 | a. If input sources are supported project files, e.g. `.csproj` or `.vbproj` files, *Project* level cache is located in file `obj/xdoc/.cache` under the same folder of the project file. 13 | 14 | b. If input sources are supported source code files, e.g. `.cs` or `.vb` files, *Project* level cache is located in file `obj/xdoc/.cache` under the same folder of the alphabetically first source code file. 15 | 16 | The cache file contains key-value pairs saved in *JSON* format. The key is the normalized input source code files, and the data structure for the value is as below: 17 | 18 | Property | Description 19 | ---------------------|-------------------------- 20 | TriggeredUTCTime | The UTC time when the action is triggered 21 | CompletedUTCTime | The UTC time when the action is completed 22 | OutputFolder | The output folder for the extracted result 23 | RelativeOutputFiles | The paths of the extracted results related to the *OutputFolder* 24 | CheckSum | The MD5 checksum calculated for all the extracted results 25 | 26 | Detailed Steps are described below: 27 | 1. For each input solution/project/source files, get most latest `LastModifiedTime`. 28 | a. For solution, get `LastModifiedTime` for the solution file, and containing projects 29 | b. For project, get `LastModifiedTime` for the project file, project references, assembly references and containing documents. 30 | c. For source files, get `LastModifiedTime` for the files 31 | 2. Normalize project list, check if *Application* level cache for these project list exists. Compare `TriggeredUTCTime` with the `LastModifiedTime` fetched in #1, and check if checksum remains unchanged for output files. If is, copy result files to output folder. Otherwise, continue to #3. 32 | 33 | 3. For each supported solution/project/source code files, 34 | 35 | *Step 1*. Check if *Project* level cache exists. If not, go to *Step 4*. 36 | 37 | *Step 2*. Compare `TriggeredUTCTime` with the `LastModifiedTime` fetched in #1, and check if checksum remains unchanged for output files. If not, go to *Step 3*. 38 | 39 | *Step 3*. Generate YAML metadata for current project and save to *Project* level cache. 40 | 41 | 4. Read YAML metadata for each project, and merge with others following rules below: 42 | 43 | *Rule 1*. For `namespace`, if `uid` equals, **append**. 44 | 45 | *Rule 2*. For other type, if `uid` equals, **override**. 46 | 47 | 5. Save result, and update **Application* level cache. 48 | -------------------------------------------------------------------------------- /samples/spec/triple_slash_comments_spec.md: -------------------------------------------------------------------------------- 1 | Triple-slash (///) Code Comments Support 2 | ========================================== 3 | DocFX extracts [triple-slash (///) code comments](https://docs.microsoft.com/en-us/dotnet/articles/csharp/programming-guide/xmldoc/xml-documentation-comments) from .NET source code when running `docfx metadata`. [Tags](https://docs.microsoft.com/en-us/dotnet/articles/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments) in triple-slash (///) code comments are converted to corresponding metadata in .NET data model. 4 | 5 | > [!NOTE] 6 | > `docfx` supports [DocFX Flavored Markdown syntax](docfx_flavored_markdown.md) inside triple-slash (///) code comments. You can disable this feature by set `shouldSkipMarkup` when generating metadata: `docfx metadata --shouldSkipMarkup`. 7 | 8 | Supported tags 9 | -------- 10 | ### Top level block tags 11 | Top level block tags are transformed to corresponding metadata in .NET data model. 12 | 13 | | Tags | Metadata name | Type 14 | | --- | --- | --- 15 | | `summary` | `summary` | `string` 16 | | `remarks` | `remarks` | `string` 17 | | `returns` | `returns` | `string` 18 | | `value` | `returns` | `string` 19 | | `exception` | `exception` | `List<`@"Microsoft.DocAsCode.DataContracts.ManagedReference.ExceptionInfo"`>` 20 | | `seealso` | `seealso` | `List<`@"Microsoft.DocAsCode.DataContracts.ManagedReference.LinkInfo"`>` 21 | | `see` | `see` | `List<`@"Microsoft.DocAsCode.DataContracts.ManagedReference.LinkInfo"`>` 22 | | `example` | `example` | `List- {buildTocNodes(toc.items)}
- {buildTocNodes(items)}