DocFx API documents
▌Introduction
We will learn how to generate API documents by DocFx
on multiple projects and publish them on a website.
▌Environment
▋Visual Studio 2017 community
▋docfx.console 2.38.1
▌Implement
▋Install docfx.console on a new website project
Lets add a new website project on your .NET solution
which contains the other target projects. I will create a clean ASP.NET MVC5
project for example.
My sample solution is as following.
MyDocFx.Web is the website with DocFx package inside, and
MyClassLibrary1 and MyClassLibrary2 are the target projects for documentation.
Install docfx.console
on the new project.
Take a look at the package, you will find docfx.exe,
which is used to generate the API documents from our source code.
In default, the documents will
be output to ./site when you build the project.
▋Install docfx tool (Optional)
We will use docfx tool to serve
the website for a quick check. However, while we are already use the website
project, you can start the website and browse the
http://localhost:<your port>/_site
to get into the DocFx website.
For docfx tool, we can simply
browse the documents on
http://localhost:<your port>
@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile
-InputFormat None -ExecutionPolicy Bypass -Command "iex
((New-Object
System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"
▋Install docfx tool
choco install docfx -y
▋Build and serve the website
Navigate to the root folder of
our website project,
$ docfx docfx.json --serve -p <port>
Then we can see the result
homepage on localhost:<port>
▋Update docfx.json
docfx.json is the key config for DocFx to know the
location of the target projects and where to output the API documents(*.html).
The original docfx.json will only build self
project,
"metadata": [
{
"src": [
{
"files": [
"*.csproj"
],
"cwd": ".",
"exclude": [
"**/obj/**",
"**/bin/**",
"_site/**"
]
}
],
"dest": "obj/api"
}
],
In src, the value of cwd indicates the
root location of the target project(s) and the value of files indicates the
including project(ex. *.csproj) or files(ex. *.cs).
Because we would like to build the other projects in
the same solution, we update docfx.json like this,
"metadata": [
{
"src": [
{
"files": [
"**/*.csproj"
],
"cwd": "../",
"exclude": [
"**/obj/**",
"**/bin/**",
"**/_site/**",
"**/MyDocFx.Web/**"
]
}
],
"dest": "obj/api"
}
],
Notice that you can set the value of files to
**/*.csproj
Or
**/*.cs
And
don’t forget to exclude the website project in exclude!
Or if you want to include more source from other
path, just give src another settings. For example, I would like to include
RouteConfig.cs in the MyDocFx.Web
project,
"metadata": [
{
"src": [
{
"files": [
"**/**.csproj"
],
"exclude": [
"**/bin/**",
"**/obj/**",
"**/_site/**",
"**/*.UnitTest/**",
"**/MyDocFx.Web/**"
],
"cwd": "../"
},
{
"files": [
"App_Start/RouteConfig.cs"
],
"exclude": [
"**/bin/**",
"**/obj/**",
"_site/**"
],
"cwd": "."
}
],
"dest": "obj/api"
}
],
Now use
DocFx command-line tool or visual studio to build and start the website, the API
documentation’s toc
(table of content) is as following.
▋Result and demo
▋Advanced: Organize the APIs
When we
have lots of different namespaces, it will be better to organize or classify
the APIs to have a friendlier document.
The final
API document page will have two API groups, the “Class Libraries” has MyClassLibrary1
and MyClassLibrary2, and the “Others” has MyDocFx.Web.
▋Update docfx.json
We are
going to set different output path for the ones in “Class Libraries” and the
other in “Others”.
"metadata": [
{
"src": [
{
"files": [
"**/**.csproj"
],
"exclude": [
"**/bin/**",
"**/obj/**",
"**/_site/**",
"**/*.UnitTest/**",
"**/MyDocFx.Web/**"
],
"cwd": "../"
}
],
"dest": "obj/api/Class Libraries"
},
{
"src": [
{
"files": [
"App_Start/RouteConfig.cs"
],
"exclude": [
"**/bin/**",
"**/obj/**",
"_site/**"
],
"cwd": "."
}
],
"dest": "obj/api/Others"
}
],
▋Update toc.yml in
root
- name: Class Libraries
href: obj/api/Class
Libraries/
- name: Others
href: obj/api/Others/
▋Demo
▌Reference
沒有留言:
張貼留言