Skip to content

Commit

Permalink
Merge branch 'move-to-new-docfx' of https://github.com/DevExpress/dot…
Browse files Browse the repository at this point in the history
…net-eud into move-to-new-docfx
  • Loading branch information
natakazakova committed Sep 25, 2024
2 parents ad39a21 + 75a422e commit e6e6c30
Show file tree
Hide file tree
Showing 5 changed files with 218 additions and 35 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/build-eud-on-pull-request.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,4 +20,4 @@ jobs:
run: Expand-Archive ../docfx-win-x64-v2.77.0.zip -DestinationPath ../docfx

- name: Build site with docfx
run: ../docfx/docfx.exe build docfx.json --warningsAsErrors
run: ../docfx/docfx.exe build docfx.json -m _matomoContainerUrl="https://matomo.devexpress.com/js/container_kE7MWPi0.js" --warningsAsErrors
2 changes: 1 addition & 1 deletion .github/workflows/update-gh-pages-branch.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ jobs:
run: Expand-Archive ../docfx-win-x64-v2.77.0.zip -DestinationPath ../docfx

- name: Build site with docfx
run: "../docfx/docfx.exe build docfx.json --metadata \"{ '_matomoContainerUrl': 'https://matomo.devexpress.com/js/container_kE7MWPi0.js' }\" --warningsAsErrors"
run: "../docfx/docfx.exe build docfx.json -m _matomoContainerUrl=\"https://matomo.devexpress.com/js/container_kE7MWPi0.js\" --warningsAsErrors"

- name: Archive site
run: Compress-Archive -Path _site/* -DestinationPath ${{ runner.temp }}/site.zip
Expand Down
169 changes: 169 additions & 0 deletions .template/layout/_master.tmpl
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
{{!Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license.}}
{{!include(/^public/.*/)}}
{{!include(favicon.ico)}}
{{!include(logo.svg)}}
<!DOCTYPE html>
<html {{#_lang}}lang="{{_lang}}"{{/_lang}}>
<head>
<meta charset="utf-8">
{{#redirect_url}}
<meta http-equiv="refresh" content="0;URL='{{redirect_url}}'">
{{/redirect_url}}
{{^redirect_url}}
<title>{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="title" content="{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}">
{{#_description}}<meta name="description" content="{{_description}}">{{/_description}}
{{#description}}<meta name="description" content="{{description}}">{{/description}}
<link rel="icon" href="{{_rel}}{{{_appFaviconPath}}}{{^_appFaviconPath}}favicon.ico{{/_appFaviconPath}}">
<link rel="stylesheet" href="{{_rel}}public/docfx.min.css">
<link rel="stylesheet" href="{{_rel}}public/main.css">
<meta name="docfx:navrel" content="{{_navRel}}">
<meta name="docfx:tocrel" content="{{_tocRel}}">
{{#_noindex}}<meta name="searchOption" content="noindex">{{/_noindex}}
{{#_enableSearch}}<meta name="docfx:rel" content="{{_rel}}">{{/_enableSearch}}
{{#_disableNewTab}}<meta name="docfx:disablenewtab" content="true">{{/_disableNewTab}}
{{#_disableTocFilter}}<meta name="docfx:disabletocfilter" content="true">{{/_disableTocFilter}}
{{#docurl}}<meta name="docfx:docurl" content="{{docurl}}">{{/docurl}}
<meta name="loc:inThisArticle" content="{{__global.inThisArticle}}">
<meta name="loc:searchResultsCount" content="{{__global.searchResultsCount}}">
<meta name="loc:searchNoResults" content="{{__global.searchNoResults}}">
<meta name="loc:tocFilter" content="{{__global.tocFilter}}">
<meta name="loc:nextArticle" content="{{__global.nextArticle}}">
<meta name="loc:prevArticle" content="{{__global.prevArticle}}">
<meta name="loc:themeLight" content="{{__global.themeLight}}">
<meta name="loc:themeDark" content="{{__global.themeDark}}">
<meta name="loc:themeAuto" content="{{__global.themeAuto}}">
<meta name="loc:changeTheme" content="{{__global.changeTheme}}">
<meta name="loc:copy" content="{{__global.copy}}">
<meta name="loc:downloadPdf" content="{{__global.downloadPdf}}">

<script type="module" src="./{{_rel}}public/docfx.min.js"></script>

<script>
const theme = localStorage.getItem('theme') || 'auto'
document.documentElement.setAttribute('data-bs-theme', theme === 'auto' ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : theme)
</script>

{{#_googleAnalyticsTagId}}
<script async src="https://www.googletagmanager.com/gtag/js?id={{_googleAnalyticsTagId}}"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag() { dataLayer.push(arguments); }
gtag('js', new Date());
gtag('config', '{{_googleAnalyticsTagId}}');
</script>
{{/_googleAnalyticsTagId}}
{{#_matomoContainerUrl}}
<!-- Matomo Tag Manager -->
<script>
var _mtm = window._mtm = window._mtm || [];
_mtm.push({'mtm.startTime': (new Date().getTime()), 'event': 'mtm.Start'});
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.async=true; g.src='{{_matomoContainerUrl}}'; s.parentNode.insertBefore(g,s);
</script>
<!-- End Matomo Tag Manager -->
{{/_matomoContainerUrl}}
{{/redirect_url}}
</head>

{{^redirect_url}}
<body class="tex2jax_ignore" data-layout="{{_layout}}{{layout}}" data-yaml-mime="{{yamlmime}}">
<header class="bg-body border-bottom">
{{^_disableNavbar}}
<nav id="autocollapse" class="navbar navbar-expand-md" role="navigation">
<div class="container-xxl flex-nowrap">
<a class="navbar-brand" href="{{_appLogoUrl}}{{^_appLogoUrl}}{{_rel}}index.html{{/_appLogoUrl}}">
<img id="logo" class="svg" src="{{_rel}}{{{_appLogoPath}}}{{^_appLogoPath}}logo.svg{{/_appLogoPath}}" alt="{{_appName}}" >
{{_appName}}
</a>
<button class="btn btn-lg d-md-none border-0" type="button" data-bs-toggle="collapse" data-bs-target="#navpanel" aria-controls="navpanel" aria-expanded="false" aria-label="Toggle navigation">
<i class="bi bi-three-dots"></i>
</button>
<div class="collapse navbar-collapse" id="navpanel">
<div id="navbar">
{{#_enableSearch}}
<form class="search" role="search" id="search">
<i class="bi bi-search"></i>
<input class="form-control" id="search-query" type="search" disabled placeholder="{{__global.search}}" autocomplete="off" aria-label="Search">
</form>
{{/_enableSearch}}
</div>
</div>
</div>
</nav>
{{/_disableNavbar}}
</header>

<main class="container-xxl">
{{^_disableToc}}
<div class="toc-offcanvas">
<div class="offcanvas-md offcanvas-start" tabindex="-1" id="tocOffcanvas" aria-labelledby="tocOffcanvasLabel">
<div class="offcanvas-header">
<h5 class="offcanvas-title" id="tocOffcanvasLabel">Table of Contents</h5>
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#tocOffcanvas" aria-label="Close"></button>
</div>
<div class="offcanvas-body">
<nav class="toc" id="toc"></nav>
</div>
</div>
</div>
{{/_disableToc}}

<div class="content">
<div class="actionbar">
{{^_disableToc}}
<button class="btn btn-lg border-0 d-md-none"
type="button" data-bs-toggle="offcanvas" data-bs-target="#tocOffcanvas"
aria-controls="tocOffcanvas" aria-expanded="false" aria-label="Show table of contents">
<i class="bi bi-list"></i>
</button>
{{/_disableToc}}

{{^_disableBreadcrumb}}
<nav id="breadcrumb"></nav>
{{/_disableBreadcrumb}}
</div>

<article data-uid="{{uid}}">
{{!body}}
</article>

{{^_disableContribution}}
<div class="contribution d-print-none">
{{#sourceurl}}
<a href="{{sourceurl}}" class="edit-link">{{__global.improveThisDoc}}</a>
{{/sourceurl}}
{{^sourceurl}}{{#docurl}}
<a href="{{docurl}}" class="edit-link">{{__global.improveThisDoc}}</a>
{{/docurl}}{{/sourceurl}}
</div>
{{/_disableContribution}}

{{^_disableNextArticle}}
<div class="next-article d-print-none border-top" id="nextArticle"></div>
{{/_disableNextArticle}}

</div>

{{^_disableAffix}}
<div class="affix">
<nav id="affix"></nav>
</div>
{{/_disableAffix}}
</main>

{{#_enableSearch}}
<div class="container-xxl search-results" id="search-results"></div>
{{/_enableSearch}}

<footer class="border-top text-secondary">
<div class="container-xxl">
<div class="flex-fill">
{{{_appFooter}}}{{^_appFooter}}<span>Made with <a href="https://dotnet.github.io/docfx">docfx</a></span>{{/_appFooter}}
</div>
</div>
</footer>
</body>
{{/redirect_url}}
</html>
64 changes: 39 additions & 25 deletions .template/partials/head.tmpl.partial
Original file line number Diff line number Diff line change
@@ -1,30 +1,44 @@
{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
{{!Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license.}}

<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}</title>
<meta name="viewport" content="width=device-width">
<meta name="title" content="{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}">
<meta name="generator" content="docfx {{_docfxVersion}}">
{{#_description}}<meta name="description" content="{{_description}}">{{/_description}}
<link rel="shortcut icon" href="{{_rel}}{{{_appFaviconPath}}}{{^_appFaviconPath}}favicon.ico{{/_appFaviconPath}}">
<link rel="stylesheet" href="{{_rel}}styles/docfx.vendor.min.css">
<link rel="stylesheet" href="{{_rel}}styles/docfx.css">
<link rel="stylesheet" href="{{_rel}}styles/main.css">
<meta property="docfx:navrel" content="{{_navRel}}">
<meta property="docfx:tocrel" content="{{_tocRel}}">
{{#_noindex}}<meta name="searchOption" content="noindex">{{/_noindex}}
{{#_enableSearch}}<meta property="docfx:rel" content="{{_rel}}">{{/_enableSearch}}
{{#_enableNewTab}}<meta property="docfx:newtab" content="true">{{/_enableNewTab}}
{{#_matomoContainerUrl}}
<!-- Matomo Tag Manager -->
{{#_googleAnalyticsTagId}}
<script async src="https://www.googletagmanager.com/gtag/js?id={{_googleAnalyticsTagId}}"></script>
<script>
var _mtm = window._mtm = window._mtm || [];
_mtm.push({'mtm.startTime': (new Date().getTime()), 'event': 'mtm.Start'});
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.async=true; g.src='{{_matomoContainerUrl}}'; s.parentNode.insertBefore(g,s);
window.dataLayer = window.dataLayer || [];
function gtag() { dataLayer.push(arguments); }
gtag('js', new Date());
gtag('config', '{{_googleAnalyticsTagId}}');
</script>
<!-- End Matomo Tag Manager -->
{{/_matomoContainerUrl}}
</head>
{{/_googleAnalyticsTagId}}
{{#redirect_url}}
<meta http-equiv="refresh" content="0;URL='{{redirect_url}}'">
{{/redirect_url}}
{{^redirect_url}}
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}</title>
<meta name="viewport" content="width=device-width">
<meta name="title" content="{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}">
{{#_description}}<meta name="description" content="{{_description}}">{{/_description}}
{{#description}}<meta name="description" content="{{description}}">{{/description}}
<link rel="shortcut icon" href="{{_rel}}{{{_appFaviconPath}}}{{^_appFaviconPath}}favicon.ico{{/_appFaviconPath}}">
<link rel="stylesheet" href="{{_rel}}styles/docfx.vendor.min.css">
<link rel="stylesheet" href="{{_rel}}styles/docfx.css">
<link rel="stylesheet" href="{{_rel}}styles/main.css">
<meta property="docfx:navrel" content="{{_navRel}}">
<meta property="docfx:tocrel" content="{{_tocRel}}">
{{#_noindex}}<meta name="searchOption" content="noindex">{{/_noindex}}
{{#_enableSearch}}<meta property="docfx:rel" content="{{_rel}}">{{/_enableSearch}}
{{#_enableNewTab}}<meta property="docfx:newtab" content="true">{{/_enableNewTab}}
{{#_matomoContainerUrl}}
<!-- Matomo Tag Manager -->
<script>
var _mtm = window._mtm = window._mtm || [];
_mtm.push({'mtm.startTime': (new Date().getTime()), 'event': 'mtm.Start'});
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.async=true; g.src='{{_matomoContainerUrl}}'; s.parentNode.insertBefore(g,s);
</script>
<!-- End Matomo Tag Manager -->
{{/_matomoContainerUrl}}
{{/redirect_url}}
</head>
16 changes: 8 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ If you search for **Developer Documentation with API Reference**, refer to [docs
## Document Format and Supported Output Types
Documents in this repository are written in markdown. You can manually copy the information to your own help file according to our [license](LICENSE.md).

The repository uses [DocFX](https://dotnet.github.io/docfx/) to convert these files from a set of markdown topics to an HTML website or a PDF file.
The repository uses [DocFX](https://dotnet.github.io/docfx/) to convert markdown files to an HTML website or a PDF file.

You can make the following changes to the documentation, or skip this step if you want to reuse the end-user documentation as is:

Expand All @@ -26,15 +26,15 @@ You can make the following changes to the documentation, or skip this step if yo
Do one of the following to view the End-User Documentation content:

1. Browse this repository's content directly: [index.md](index.md)
1. View the sample pre-built website: [devexpress.github.io/dotnet-eud](https://devexpress.github.io/dotnet-eud/)
1. View the pre-built sample website: [devexpress.github.io/dotnet-eud](https://devexpress.github.io/dotnet-eud/)
1. [Build an HTML Website](#build-an-html-website)
1. [Build PDF files](#build-pdf-files)

### Build an HTML Website

> Prerequisites
> - Familiarity with the command line
> - Install [.NET SDK](https://dotnet.microsoft.com/en-us/download) 6.0 or higher
> - [.NET SDK](https://dotnet.microsoft.com/en-us/download) 6.0 or higher
> - [Git](https://git-scm.com/)
Make sure you have [.NET SDK](https://dotnet.microsoft.com/en-us/download) installed, then open a terminal and enter the following command to install the latest DocFX:
Expand All @@ -61,20 +61,20 @@ To preview changes, open a console window and call the `docfx build` command wit
```bash
docfx build D:/dotnet-eud/docfx.json --serve
```
Docfx produces static HTML files under the _site folder ready for publishing to any static site hosting servers. Deploy the created documentation to a web server or browse the documentation directly from local file system. To begin, you can refer to the DocFX documentation: [Publish to GitHub Pages](https://dotnet.github.io/docfx/index.html#publish-to-github-pages).
DocFX produces static HTML files under the *_site* folder ready to publish to any static site hosting server. Deploy the created documentation to a web server or browse the documentation directly from the local file system. For more information, refer to the DocFX documentation: [Publish to GitHub Pages](https://dotnet.github.io/docfx/index.html#publish-to-github-pages).

### Build PDF Files
If your end users require a printed version, you can build a PDF file.

You can configure PDF file generation in several ways.

The resulted PDF file will be located near *toc.yml* in the *_site* folder.
The resulted PDF file will be located next to the *toc.yml* file in the *_site* folder.

#### Build locally
#### Build Locally

Open the console and call `docfx pdf D:\test-eud\docfx.json`. You need a succeeded build before you proceed.

#### docfx.json
#### Use docfx.json

Include the `pdf` command to _docfx.json_.

Expand Down Expand Up @@ -102,7 +102,7 @@ You can generate PDF only for a specific _toc.yml_:
}
```

#### toc.yml
#### Use toc.yml

Include the `pdf` command to _toc.yml_ to generate PDF according to this table of content:

Expand Down

0 comments on commit e6e6c30

Please sign in to comment.