In this post, we’ll use DocFx to produce documentation for a Visual Studio C# solution in a Windows machine.
Table of Contents
- Introduction
- DocFx Installation
- A Test Solution in Visual Studio
- Setting up DocFx with docfx init
- Setting up DocFx Manually
- The Anatomy of the docfx.json Configuration File
- The metadata Section
- The build Section
- The docs Folder
- The filterConfig.yml File
- Conceptual Documentation and the TOC (Table Of Content) Files
- The .gitignore File
- Generate the Documentation Site
- Publish the Generated Documentation Site to GitHub Pages
- The PDF Adventure
- History
Introduction
DocFx is a command line tool that generates documentation.
DocFx builds a documentation web site combining two sources:
- reference documentation it collects from comments found in source code files
- conceptual documentation provided to DocFx as Markdown files, by the user
According to DocFx web site:
"DocFX can produce documentation from source code (including .NET, REST, JavaScript, Java, Python and TypeScript) as well as raw Markdown files."
and also:
"DocFX can run on Linux, macOS, and Windows. The generated static website can be deployed to any host such as GitHub Pages or Azure Websites with no additional configuration."
DocFx is an open source tool developed by Microsoft and, as the company says, is a tool used in building Microsoft's documentation web site.
In this post, we'll use DocFx to produce documentation for a Visual Studio C# solution in a Windows machine.
DocFx Installation
The easiest way to download and install DocFx is to use the Chocolatey package manager for Windows. Open a terminal as administrator and execute the following:
choco install docfx -y
The above adds the DocFx to the PATH environment variable too.
A Test Solution in Visual Studio
Open Visual Studio and create a solution with two projects: a Library project and a Windows Forms project.
Here is the folder structure:
Solution + App + Lib Solution.sln
For each project, go to Properties | Build and check the XML documentation file check box.
Add some classes to both projects and document those classes. This is done by adding triple-slash comments to classes, methods and properties.
Build the solution.
Setting up DocFx with docfx init
The DocFx documentation provides two walkthroughs.
Those walkthroughs say that we init the DocFx by opening a terminal, cd to solution folder and then type docfx init -q to initialize the project.
cd C:\Solutiondocfx init -q
The -q parameter is for quiet. Otherwise, it goes through a series of questions the user has to answer.
The above creates a docfx_project folder inside the root solution folder and adds a number of sub-folders and files to it. The most important file inside that docfx_project is the docfx.json file which is the configuration file for the DocFx.
"docfx.json is the configuration file docfx uses to generate documentation"
All folder references inside that generated docfx.json are wrong. And some of the created folders are not needed at all.
Therefore, delete the docfx_project folder. We are going to use our own way.
Setting up DocFx Manually
We need a sub-folder inside the root solution folder for the DocFx files and generated documentation. Create the new folder and name it DocFx.
Solution + App + DocFx + Lib Solution.sln
Inside DocFx folder, create an empty docfx.json, open it with Visual Studio and add the following content:
{ "metadata": [ { "src": [ { "files": [ "**/**.csproj" ], "src": ".." } ], "dest": "reference", "disableGitFeatures": false, "disableDefaultFilter": false, "filter": "filterConfig.yml" } ], "build": { "content": [ { "files": [ "reference/**.yml", "reference/index.md" ] }, { "files": [ "Concepts/toc.yml", "Concepts/**.md", "Concepts/**/toc.yml", "toc.yml", "*.md" ] } ], "resource": [ { "files": [ "images/**" ] } ], "dest": "../docs", "globalMetadataFiles": [], "fileMetadataFiles": [], "template": [ "default" ], "postProcessors": [], "markdownEngineName": "markdig", "noLangKeyword": false, "keepFileLink": false, "cleanupCacheHistory": false, "disableGitFeatures": false }}The Anatomy of the docfx.json Configuration File
The docfx.json contains two sections: metadata and build. There can be a third section, pdf, but we leave that ...adventure for a later time.
The metadata Section
The metadata section says to DocFx:
- where to find source code files, to gather comments from
- where to place the gathered material
- and how to filter inderited members of types found in source files
Our metadata section says to DocFx:
- to look for source code files in all
csprojfiles ("files": [ "**/**.csproj" ]) starting from the rool solution folder ("src": "..") - place the gathered material to a folder named
reference("dest": "reference",) - and filter inherited members according to a provided
ymlfile ("filter": "filterConfig.yml")
The reference folder will be created by DocFx if not there.
The Build Section
The build section says to DocFx:
- where to find the content to build, for both types, the content DocFx gathered from source files (reference) and the content provided by the user as Markdown files (conceptual)
- where to find the images used in Markdown files
- where to place the "compiled" output, meaning the web site it generates
- and what template to use
Our build section says to DocFx:
- the reference content is found in the reference folder while the conceptual is found in the Concepts folder
- the images are in the images folder
- place the generated site to the ../docs folder (
"dest": "../docs") - and use the
defaulttemplate
The docs Folder
We instruct DocFx to place the generated web site in a docs folder, under the root solution folder. This will result in the following folder structure:
Solution + App + DocFx + docs + Lib Solution.sln
You can instruct DocFx to place the generated site in any folder you like.
We name that folder docs and place it under the root solution folder because GitHub Pages want it like that.
If you use github to host your open source project and you want to provide a nice documentation site for your project, you can achieve that easily by simply placing the documentation site inside the docs folder under the root and setting that docs folder as the publishing source for the GitHub Pages site.
The filterConfig.yml File
As the DocFx documentation says:
"A filter configuration file is in YAML format. You may filter out unwanted APIs or attributes by providing a filter configuration file and specifying its path."
Place a filterConfig.yml with the following content:
apiRules:- exclude: # inherited members from Form uidRegex: ^System\.Windows\.Forms\.Form\..*$ type: Member- exclude: # inherited members from Control uidRegex: ^System\.Windows\.Forms\.Control\..*$ type: Member- exclude: # mentioning types from System.* namespace uidRegex: ^System\..*$ type: Type- exclude: # mentioning types from Microsoft.* namespace uidRegex: ^Microsoft\..*$ type: Type
CAUTION: The lines containing the
uidRegexandtypeentries should start with two spaces. YAML language uses white space indentation.
Conceptual Documentation and the TOC (Table Of Content) Files
DocFx accepts Markdown files containing conceptual documentation, written by the user. Organizes those Markdown files using TOC (Table Of Content) YAML files.
Under the DocFx folder, add an index.md file with whatever content you like.
Here is my DocFx folder:
DocFx docfx.json index.md .gitignore filterConfig.yml toc.yml
Inside the DocFx folder, create a Concepts sub-folder and add the following folders and files:
Concepts + Advanced Abstract.md Advanced.md toc.yml + Easy Abstract.md Easy.md toc.yml Abstract.md toc.yml
You may place whatever content you like in these Markdown files. Usually, those files contain conceptual overviews regarding the use of the referenced API.
Regarding TOC files, you may consult the relevant DocFx documentation which says that:
"DocFX supports processing Markdown files or Conceptual Files, as well as structured data model in YAML or JSON format or Metadata Files. Besides that, DocFX introduces a way to organize these files using Table-Of-Content Files or TOC Files, so that users can navigate through Metadata Files and Conceptual Files."
Listed below are the three toc.yml files used:
- Concepts/toc.yml:
- name: Easy href: Easy/toc.yml topicHref: Easy/Abstract.md- name: Advanced href: Advanced/toc.yml topicHref: Advanced/Abstract.md
- Concepts/Advanced/toc.yml:
- name: Advanced Overview Title href: Advanced.md
- Concepts/Easy/toc.yml:
- name: Easy Overview Title href: Easy.md
The
nameentry is the clickable title, i.e., link, to be displayed by the TOC of the generated site.The
hrefentry says where to navigate when that title is clicked.The optional
topicHrefsays what content file to display. Used when thehreflinks to another toc.yml, that is another Table Of Contents, but the user wants to provide some kind of abstraction to the visitor, as to what she/he is going to find in that link.
The .gitignore File
The docfx init -q command adds a .gitignore file inside the DocFx folder. Create a .gitignore file with the following content and place it into the DocFx folder.
/**/DROP//**/TEMP//**/packages//**/bin//**/obj/reference
Generate the Documentation Site
In order to generate the web site, open a terminal, cd to DocFx folder and just type:
docfx
The web site is generated.
It's time to preview the site. According to the documentation:
"If port 8080 is not in use, docfx will host _site under http://localhost:8080. If 8080 is in use, you can use docfx serve _site -p <port> to change the port to be used by docfx."
To preview the site, cd to docs:
cd ../docs
and then type:
docfx serve
or if the port 8080 is taken by another application, just use another port:
docfx serve -p 8081
Now the documentation site is running.
Open a browser and navigate to http://localhost:8080.
Alternatively, if you place the folder of the generated site under the DocFx folder, you may build and run the site with just a single line.
docfx --serve
You may delete the generated folders, reference and docs. They are recreated in each build.
Publish the Generated Documentation Site to GitHub Pages
Pushyour local git repository to your github remote repository.- In github repository, go to Settings (it's far right with the gear icon).
- Scroll down to GitHub Pages section.
- Select master branch /docs folder as Source.
- Do NOT select theme.
That's all. Your documentation site will be available soon, if not immediately, at:
`https://USER_NAME.github.io/PROJECT_NAME/`
The PDF Adventure
DocFx can generate a single PDF file, for the whole generated documentation. Not without problems.
DocFx generates the PDF output using the wkhtmltopdf tool.
To download and install wkhtmltopdf, open a terminal as administrator and type:
choco install wkhtmltopdf -y
In order to generate the coveted PDF file, the user has to read and ...understand the relevant documentation provided by DocFx.
One piece of that information can be found in the user manual while the other can be found in the third walkthrough.
Here is my way, after a lot of digging and experimenting:
- Add a PDF folder inside DocFx folder
- Add the following toc.yml inside PDF folder:
- name: Concepts href: ../Concepts/toc.yml- name: Reference href: ../reference/toc.yml
- Add a
pdfsection in the docfx.json with the following content:"pdf": { "content": [ { "files": [ "PDF/toc.yml" ] }, { "files": [ "reference/**.yml", "reference/index.md" ], "exclude": [ "**/toc.yml", "**/toc.md" ] }, { "files": [ "Concepts/**.md", "Concepts/**/toc.yml", "toc.yml", "*.md" ], "exclude": [ "**/bin/**", "**/obj/**", "PDF/**", "**/toc.yml", "**/toc.md" ] } ], "resource": [ { "files": [ "images/**" ], "exclude": [ "**/bin/**", "**/obj/**", "PDF/**" ] } ], "dest": "_pdf", "outline": "NoOutline"} - Open a terminal,
cdto DocFx folder and type:docfx pdf
This will generate a PDF file, without outline, meaning PDF TOC. Obviously, there is a problem and the outline is not correctly generated. So I deactivated using the
"outline": "NoOutline".(Video) Make awesome looking documentation site with an open source Docsify and GitHub Page
Tested on
- Windows 10
- docfx 2.48.1.0
- wkhtmltopdf 0.12.5 (with patched qt)
History
- 17th February, 2020: Initial version
I’m a (former) musician, programmer, wanna-be system administrator and grandpa, living in Thessaloniki, Greece.
FAQs
How to use Docfx? ›
Use DocFX as a command-line tool
Download and unzip docfx. zip from https://github.com/dotnet/docfx/releases, extract it to a local folder, and add it to PATH so you can run it anywhere. This command generates a default project named docfx_project . Now you can view the generated website on http://localhost:8080.
When it comes to documentation, a path with less resistance is often the better approach. GitHub Pages gives you a direct path to create websites for your projects, which makes it a natural choice for publishing and maintaining documentation.
What is the difference between GitHub docs and pages? ›GitHub Pages can be classified as a tool in the "Static Web Hosting" category, while Read the Docs is grouped under "Documentation as a Service & Tools". Some of the features offered by GitHub Pages are: Blogging with Jekyll.
Can Docfx generate markdown? ›Markdown Extensions
Docfx supports additional markdown syntax that provide richer content. These syntax are specific to docfx and won't be rendered elsewhere like GitHub.
Alternatively, you can download and unzip docfx. zip from https://github.com/dotnet/docfx/releases, extract it to a local folder, and add it to PATH so you can run it anywhere. This command generates a default project named docfx_project . Now you can view the generated website on http://localhost:8080.
How do you add a mermaid to DocFX? ›While DocFX does not support using Mermaid out of the box, there is an option you can use to leverage this powerful tool. To use Mermaid in your DocFX project you will need to extend the default template. To do this simply add a new folder called mermaid in the template folder.
How do I make a good documentation on GitHub? ›- Organizing information with tables.
- Organizing information with collapsed sections.
- Creating and highlighting code blocks.
- Creating diagrams.
- Writing mathematical expressions.
- Autolinked references and URLs.
- Attaching files.
- About task lists.
GitHub is like your Google Docs, except you can create & save your version of the code offline, before 'pushing' it to be saved online. So, you have your text editor (Atom), version control system (Git) & remote file storage system (GitHub).
What should I not upload to GitHub? ›- any content which does not legally belong to you, and which has no some open source license.
- content which could be generated (e.g. object files).
GitHub Pages is a great option for hosting your production environment, because it is free to use, reliable, and requires no maintenance. The setup process is fairly similar to the quick start procedure, but requires a bit more explanation.
Why should I use GitHub Pages? ›
It allows you to upload code repositories for storage in the Git version control system. You can then collaborate on code projects, and the system is open-source by default, meaning that anyone in the world can find your GitHub code, use it, learn from it, and improve on it.
Is pages or docs better? ›Google Docs supports a lot more formats compared to iCloud Pages. Things also work the other way. If I have a Word or text document that I'd like to edit, all I need to do is to upload it to Google Drive or iCloud Drive, and then access it using Docs or Pages.
Can you make a website with Markdown? ›Building your first website
Open up RStudio and go to File -> New Project -> New Directory -> Simple R Markdown Website and then fill in the following boxes to name and save your website source code wherever you would like. After you click “Create Project”, you should see three files in your RStudio window: _site.
Markdown is easier to write than HTML, and it's easier for most humans to read Markdown source than HTML source. However, HTML is more expressive (particularly regarding semantic tagging) and can achieve some specific effects that might be difficult or impossible in Markdown.
Can Markdown be converted to HTML? ›Output. A Markdown to HTML converter is a tool that takes Markdown formatted text and converts it into HTML. This can be useful for people who want to write in a more readable and lightweight markup language, but need to display their text on the web.
Is read the docs free? ›Our code is free and open source. Our company is bootstrapped and 100% user focused. Read the Docs Community hosts documentation for over 100,000 large and small open source projects, in almost every human and computer language.
How do I download Jsdoc? ›- Install Node.js which comes with npm.
- Open a command line.
- Install JsDoc by typing the following command: npm install -g jsdoc.
- Run JsDoc / generate documentation. more info jsdoc path/to/file.js.
- Configure jsdoc (Optional)
DocFX Document Schema is in JSON format. It borrows most syntax from JSON Schema, while it also introduces some other syntax to manipulate the data.
How do I get a mermaid publisher? ›| Publisher | Sourcebooks Wonderland (March 26, 2020) |
|---|---|
| Paperback | 40 pages |
| ISBN-10 | 1728234247 |
| ISBN-13 | 978-1338565485 |
| Reading age | 3 - 6 years, from customers |
Plain Text Files Make Things Easy
Git and GitHub do commits on pretty much any file type for writing, although it works best with plain text. If you write in Microsoft Word, it'll work, but you won't be able to see your past commits on the command line or in GitHub.
How do I use technical documentation on GitHub? ›
- Actions. Automate any workflow.
- Packages. Host and manage packages.
- Security. Find and fix vulnerabilities.
- Instant dev environments.
- Copilot. Write better code with AI.
- Manage code changes.
- Issues. Plan and track work.
- Discussions. Collaborate outside of code.
Push the files to Github
Make sure to initialize the repository with a README file. Once you're in your new repository, click Upload files: Drag and drop in your files and click Commit changes: Alternatively, you could use Github Desktop or the command line to commit files to your repository.
GitHub offers free and paid products for storing and collaborating on code. Some products apply only to personal accounts, while other plans apply only to organization and enterprise accounts. For more information about accounts, see "Types of GitHub accounts."
Is it illegal to copy code from GitHub? ›If you want others to use, distribute, modify, or contribute back to your project, you need to include an open source license. For example, someone cannot legally use any part of your GitHub project in their code, even if it's public, unless you explicitly give them the right to do so.
What is the disadvantage of GitHub? ›Potential Drawback: Difficult To Use For Beginners
New users can find the many different options and ways of doing things in GitHub confusing and overwhelming. In particular, many people struggle with GitHub's many unintuitive commands and the inconsistency between commands and arguments in the software.
File size limits
GitHub limits the size of files allowed in repositories. If you attempt to add or update a file that is larger than 50 MB, you will receive a warning from Git. The changes will still successfully push to your repository, but you can consider removing the commit to minimize performance impact.
Cons of Github
Github is a public repository platform so anyone with a Github account can access the source codes. If you want to access the versioning repository you need to subscribe to the Github.com premium account. Github repository does not offer the proper testing services.
Even if the repository is private, the site is still publicly available on the internet — so the developer should always check for any sensitive data before deployment. Naturally, sending sensitive data (e.g. passwords or credit card information) is also unsafe.
Is there anything better than GitHub? ›If we compare GitHub with its alternatives, then each tool has its pros and cons. Like Apache Allura, Git Bucket, and Gitea are completely free and open-source with their unique features for different needs. The other tools like GitLab, Git Kraken, and Bitbucket are not open-source but they also have free plans.
How long does GitHub Pages take to publish? ›Note: It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub. If you don't see your GitHub Pages site changes reflected in your browser after an hour, see "About Jekyll build errors for GitHub Pages sites."
How many pages can you have on GitHub Pages? ›
For each registered GitHub account (representing a user or an organization) you can register one User Page, but an unlimited Project pages.
What does a good GitHub page look like? ›A good GitHub profile shows frequent and consistent contributions throughout the year, both to personal projects and to others' projects. GitHub publicly displays the user's current streak of work — the number of days in a row that the user made contributions to a project — and the user's longest streak.
How do I deploy a website to GitHub? ›Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings. In the "Code and automation" section of the sidebar, click Pages. Under "Build and deployment", under "Source", select Deploy from a branch.
Is Pages as good as publisher? ›Reviewers felt that Pages meets the needs of their business better than Microsoft Publisher. When comparing quality of ongoing product support, reviewers felt that Pages is the preferred option. For feature updates and roadmaps, our reviewers preferred the direction of Pages over Microsoft Publisher.
Is there anything better than Google Docs? ›- ClickUp. ClickUp is the world's highest-rated productivity and document collaboration software used by several teams in small and large companies. ...
- Microsoft Office Online. Via Microsoft Office. ...
- Zoho Docs. Via Zoho Docs. ...
- Dropbox Paper. Via Dropbox Paper. ...
- Apache OpenOffice. ...
- Obsidian. ...
- Evernote. ...
- Coda.
Pages puts all the right tools in all the right places, so it's easy to choose a look, customize fonts, personalize text styles, and add beautiful graphics. And everyone collaborating on a document has access to the same powerful features.
Do people still use Markdown? ›Markdown is widely used, and because it's just ASCII text after all, it is future-proof. When our descendants are trying to figure out how to read a PDF file, Markdown will still be sitting there out in the open like a Rosetta stone. By the way, since it's just text, it's easy to manage with any source control tool.
Is Markdown worth learning? ›Markdown is Highly Portable
One of the most significant advantages to writing in Markdown is how easy it is to convert Markdown into virtually any other file format: HTML: With no knowledge or experience in web development, you can quickly convert Markdown to HTML. There are many ways to convert Markdown to HTML.
Many technical writers find lots of benefits in using Markdown for their documentation. Some of these benefits are: Markdown provides semantic meaning for content in a relatively simple way. You can write rich formatted content extremely quickly (compared to writing directly in HTML tags)
Why do people like Markdown? ›Markdown gets rid of all the distractions of a formatting toolbar and mouse clicks by helping you focus on your writing without lifting your fingers off of the keyboard. Advanced writers love this kind of seamless experience which allows them to stylize their text on the fly.
How long does it take to learn Markdown? ›
Markdown is easy to learn. Super easy. You can learn the basics in five minutes and it will quickly become second nature. And – just like the relationship between CSS and CSS preprocessors – you can use as little or as much as you like.
Is HTML best for web development? ›HTML is at the core of every web page, regardless the complexity of a site or number of technologies involved. It's an essential skill for any web professional. It's the starting point for anyone learning how to create content for the web.
Can you convert doc to HTML? ›Using MS Word built-in save as HTML option
Go to the file menu. Select Save as. In the drop-down file type box select, Web Page, Filtered. Click Save.
First, open the Command Palette by pressing CTRL+SHIFT+P . Then, start typing in “Markdown” and click on the Markdown All in One: Print current document to HTML command. The image below shows how the HTML formatting looks like after exporting the Markdown document.
What does github use to convert Markdown to HTML? ›Markdown is converted to HTML by the comrak crate. The default stylesheet (the CSS file) is from sindresorhus/github-markdown-css. If ``` is used in the input Markdown file, the highlight. js will be automatically embedded in the output HTML file.
Can I use Git to manage documents? ›Because the files are stored in Git as plain text, it is easy to include documentation changes in your merge requests. The web interface of your Git repository will automatically convert the Markdown format to a nicely formatted page for everyone to read.
What is GitHub best used for? ›GitHub is an online software development platform. It's used for storing, tracking, and collaborating on software projects. It makes it easy for developers to share code files and collaborate with fellow developers on open-source projects.
Can GitHub be used for Word documents? ›Plain Text Files Make Things Easy
Git and GitHub do commits on pretty much any file type for writing, although it works best with plain text. If you write in Microsoft Word, it'll work, but you won't be able to see your past commits on the command line or in GitHub.
We would absolutely recommend that you learn how to put GitHub on your resume since it can be one of the best ways to demonstrate your skills and experience to hiring managers. Since coding is such a technical profession, it can often be difficult to verify your real skills to potential employers.
Can GitHub be used as a document management system? ›Is Github a document management system? Github document management refers to the management of documentation for software projects that are created and hosted on Github. You can use Github for private or open-source document management.
Why is product documentation important to people who use GitHub? ›
Providing well-written documentation helps people understand, make use of, and contribute back to your project, but it's only half of the documentation equation. The underlying system used to serve documentation can make life easier for the people writing it—whether that's just you or the team you work with.
Do technical writers use GitHub? ›More and more, writers are being asked to use Git and GitHub for their documents. This is part of a philosophy called "Docs Like Code", where documentation is created using the same tools and processes that code is.
Is GitHub used professionally? ›Github is used by professionals and companies for smoother collaboration on software development projects. If you're an aspiring professional programmer or software developer, learning Github is an essential skill that will add value to your resume.
What is difference between Git and GitHub? ›While Git is a tool that's used to manage multiple versions of source code edits that are then transferred to files in a Git repository, GitHub serves as a location for uploading copies of a Git repository. In a sense, then, there's no comparison when it comes to Git vs. GitHub as far as their function.
Should beginners use GitHub? ›Whether you are working on personal projects alone or are part of a team working on huge enterprise software, GitHub is a useful tool. If you're alone, you can use it to store your code and show off what you've done to others.
Does GitHub support docx? ›GitHub is just a back end repository store that can be used to store Git data. Microsoft Word Documents have in-band markup, along with the text data, and are stored as binary files — this is true for both . doc and . docx files.
How do I Upload a Google Doc to GitHub? ›...
Google Docs documents
- Sign in to your Goole Docs account.
- Open the document that you want to embed.
- Click File -> Publish to the web.
- Copy the link from the "Document link" field.
- Paste the link between the google_docs tags.
Prohibited uses
GitHub Pages is not intended for or allowed to be used as a free web-hosting service to run your online business, e-commerce site, or any other website that is primarily directed at either facilitating commercial transactions or providing commercial software as a service (SaaS).
GitHub has become an essential tool for many developers and tech professionals, providing a platform to showcase their skills, experience, and portfolio of work. As a result, hiring managers and recruiters often turn to GitHub profiles when evaluating candidates.
What does a good GitHub look like? ›A good GitHub profile shows frequent and consistent contributions throughout the year, both to personal projects and to others' projects. GitHub publicly displays the user's current streak of work — the number of days in a row that the user made contributions to a project — and the user's longest streak.
Is it better to use Git or GitHub? ›
what's the difference? Simply put, Git is a version control system that lets you manage and keep track of your source code history. GitHub is a cloud-based hosting service that lets you manage Git repositories. If you have open-source projects that use Git, then GitHub is designed to help you better manage them.