[
https://issues.apache.org/jira/browse/TINKERPOP-2018?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16694664#comment-16694664
]
Florian Hockmann commented on TINKERPOP-2018:
---------------------------------------------
Nice, looks great! I'm also not that familiar yet with DocFX, but I'll try to
answer your questions.
{quote}1. I duplicated the
[index.md|https://github.com/apache/tinkerpop/commit/1b38ebd4f5b320a0dcecc6fa0b3047434e8cbc95#diff-5d1b9ad1ce95edb529c8244c23d3a526]
- it's a copy of {{README.md}}. I guess we should have on or the other and not
both or write a different set of content for the API docs. Personally, i
wouldn't mind if we got rid of a "landing" page all together and just had the
API docs front/center but I couldn't figure out how to make that work.
{quote}
I just tried to remove the {{index.md}}, but couldn't get a good result.
Doesn't seem to be trivial to accomplish this. I guess we could reference the
{{README.md}} if we would move at least the {{docfx.json}} one layer up (as it
doesn't allow the inclusion of elements from other directories). Then we would
probably only have to figure out how we could use the {{README.md}} as an
\{{index.html}}. I also asked about this in their [Gitter
chat|https://gitter.im/dotnet/docfx], maybe someone in there has a good
solution.
{quote}2. Not sure how to get our logo to replace that "D" logo
3. Not sure how best to kill the "D" .{{favicon}} - doesn't matter if we have
one or not, just would rather not have a "D"
{quote}
[Their docs mention two
fields|https://dotnet.github.io/docfx/tutorial/docfx.exe_user_manual.html?q=_appLogoPath#322-reserved-metadata]:
{{_appLogoPath}} for the logo in the top and {{_appFaviconPath}} for the
favicon. I guess we want to replace both (with TinkerPop's or Gremlin.Net's
logo?).
{quote}4. Not sure if _site where the docs are generated should be in
/target/_site
{quote}
Sounds like a good idea to me, but I don't have a strong opinion on that as
{{target}} is Maven specific and we didn't really use that until now for the
other .NET resources so we could also keep {{_site}} where it is right now. In
general, you probably want to add the path to the rats ignore section in top
level {{pom.xml}}. Otherwise, it will complain about missing licenses in the
generated HTML files.
{quote}5. There this "Improve this Doc" link on the "landing page" - not sure
how to kill that
{quote}
Setting {{_disableContribution}} to {{true}} [should disable
this|https://dotnet.github.io/docfx/tutorial/docfx.exe_user_manual.html#322-reserved-metadata].
> Generate API docs for Gremlin.Net
> ---------------------------------
>
> Key: TINKERPOP-2018
> URL: https://issues.apache.org/jira/browse/TINKERPOP-2018
> Project: TinkerPop
> Issue Type: Improvement
> Components: build-release, documentation, dotnet
> Reporter: Florian Hockmann
> Assignee: stephen mallette
> Priority: Major
> Attachments: junk.png
>
>
> Similar to TINKERPOP-2010 which handles doc generation for
> gremlin-javascript, we should also generate and publish API docs for
> Gremlin.Net. We already have the necessary XML documentation comments in
> place for this.
> The docs could be generated with [DocFX|https://dotnet.github.io/docfx/]
> which I already used for [the API docs of the old pre-TinkerPop version of
> Gremlin.Net|https://florianhockmann.github.io/Gremlin.Net/api/Gremlin.Net.html].
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
