CSHARP-4783: API docs generating with docfx #1206
Conversation
sanych-sun
requested review from
adelinowona and
JamesKovacs
and removed request for
a team and
adelinowona
There was a problem hiding this comment.
This looks great. Minor feedback on naming. As well since this commit replaces Sandcastle with DocFX, we should remove the ./Docs folder as part of this commit. I realize that this will remove both the Sandcastle-related files as well as the reference docs. The reference docs aren't related, but we stopped updating them awhile ago.
.gitignore
Outdated
| @@ -68,3 +68,5 @@ artifacts | |||
| packages | |||
| /tools | |||
| /evergreen/krb5.conf.empty | |||
| /build | |||
There was a problem hiding this comment.
Other tasks build into the artifacts directory. We should use that rather than adding another directory.
There was a problem hiding this comment.
Ups, I've discovered that test results file being output into the ./build directory and did not check if other tasks output to the same folder. Will update here and some another tasks (packages creation script also output to the ./build folder now, will update it to use ./artifacts folder).
docfx_project/api/index.md
Outdated
| @@ -0,0 +1 @@ | |||
| # MongoDB C# Driver API Reference | |||
There was a problem hiding this comment.
MongoDB .NET/C# Driver API Reference
evergreen/apidocs-build.sh
Outdated
| @@ -0,0 +1,12 @@ | |||
| #!/usr/bin/env bash | |||
There was a problem hiding this comment.
Most of our other scripts use verb-noun.sh. Consider changing this to build-apidocs.sh.
There was a problem hiding this comment.
I probably would like to review this naming convention. If we use opposite convention: noun-verb.sh this let us group together related scripts. For example:
apidocs-build
apidocs-validate
packages-pack
packages-push
packages-test
tests-run
Let's discuss it with the team.
There was a problem hiding this comment.
I've reviewed other drivers/repos: all of them are using verb-noun.sh notation. I'll update scripts to follow the same naming conventions. Thanks.
evergreen/evergreen.yml
Outdated
| @@ -1305,7 +1305,7 @@ tasks: | |||
|
|
|||
| - name: atlas-search-index-helpers-test | |||
| commands: | |||
| - func: run-atlas-search-index-helpers-test | |||
There was a problem hiding this comment.
Unrelated change even if it is fixing whitespace.
docfx_project/.gitignore
Outdated
| @@ -0,0 +1,2 @@ | |||
| .manifest | |||
There was a problem hiding this comment.
As we removed "old" Docs folder, should we rename this folder to Docs instead of docfx_project?
evergreen/evergreen.yml
Outdated
| @@ -47,7 +47,7 @@ functions: | |||
| fi | |||
There was a problem hiding this comment.
I've applied proper naming to all recently added scripts/tasks. Also I'll create a separate green-build-friday task to implement CI step to call docfx.
There was a problem hiding this comment.
Cake includes a DocFX add-in. We should keep the ApiDocs task and use that add-in. If we decide to replace Cake entirely with shell scripts eventually, we can do it then. But for now we should keep the Cake tasks for consistency.
sanych-sun
force-pushed
the
doc_fx
branch
4 times, most recently
from
2fcd099 to
10d5c9c
Compare
Here is an example of generated site: https://sanych-sun.github.io/mongo-csharp-driver/api/index.html