markdig
markdig copied to clipboard
xoofx
Add DocFX Documentation
Since the API looks well commented with XML comments, it'd be handy at least until full example documentation could be written, to have a DocFX site for at least the API docs.
This could make it a bit easier to see a breakdown and relations of certain API calls and the relations between objects and such.
Thanks!
Since the API looks well commented with XML comments, it'd be handy at least until full example documentation could be written, to have a DocFX site for at least the API docs. This could make it a bit easier to see a breakdown and relations of certain API calls and the relations between objects and such.
So I wanted to do that in the past, but there are a few reasons why I haven't:
- The API docs are really not enough, so providing a docfx site would require to also provide quite a bit of user-guide documentation. I also prefer to expose a handcrafted VS class diagram of the model rather than just the API docs (to quickly grasp and understand the relations).
- The default DocFx theme is a bit awful look-wise and seems to be laborious to modify (lack of time and energy myself to do that)
So ideally, that would be nice, but it is quite a bit of work.
@xoofx anything at this point is better than nothing. Just having a site (even if I have to run a step to use DocFX myself) that links all the APIs together and a paragraph with a couple of links to the key entry points would be appreciated.
What about sandcastle ? It generates MSDN like docs without much hastle.
I have used sandcastle year ago, it was not bad, but it was not good enough in many areas (styling, slow...etc.) that I had to develop my own doc system back in the days (called SharpDoc)
More than API, it is a proper documentation that is required. I don't believe exposing the API would help anything here. You need to understand the dependencies, you need to have some examples, you need to go through the API main classes, explain the hierarchy, the why, how to do some basic stuffs...etc. There are hundred of classes details in Markdig, only a very marginal part of the API is relevant to go through to get an idea about how things are working.
I'm already working on a website for another project, so can't work on this right now. I might come back to markdig once I have released the other project, but can't tell when.
@xoofx - I might have a hybrid solution - especially for the user guide as I faced similar problems (theme not good enough, API is not as important as a user guide, etc.) and ended up developing my own system just like you. Would love to have a conversation about it whenever you have time. I'd also be happy to help contribute by maintaining the docs whenever required.
@daxpandhi yeah, I have been able to release the website kalk I was working on, and I have upgraded my blog post as well using lunet. I'm close to have API generated doc with Lunet, so I might be able to push markdig website in the coming months. it's a bit low priority in my sparetime, but that should hopefully come later this year.
Hi @xoofx. I'm part of a project that is building a new static site generator. https://retype.com
Our project is actually using Markdig for markdown processing and built on C#. I noticed this thread and thought I would try generating a website and the API reference for Markdig.
https://geoffreymcgill.github.io/markdig/
The site above is generated from a fork of the main Markdig repo: https://github.com/geoffreymcgill/markdig
Still lots of stuff we need to work on with Retype, but I thought the Markdig site looked pretty good. 😄
Thought you might be interested.
I sent the setup as a PR, see https://github.com/xoofx/markdig/pull/545
No worries if there is no interest.
Still lots of stuff we need to work on with Retype, but I thought the Markdig site looked pretty good. 😄
Thanks! You've got a really nice, clear and sharp theme.
Unfortunately, as I mentioned above, I will have to decline mainly because I would like to push the website with my own lunet static website generator. More a lack of time to push this website than technical limitations.