search

dart-lang / dartdoc

API documentation tool for Dart.
https://pub.dev/packages/dartdoc
BSD 3-Clause "New" or "Revised" License
473 stars 118 forks source link

add plugin support for custom generators to dartdoc #2788

Open EhsanAramide opened 2 years ago

EhsanAramide commented 2 years ago

Hi maintainers!

The dartdoc just supports two generators, markdown and html, do you have any plan to create a generator for generating json output besides html or markdown? Or even a way for creating custom generators by ourselves for Dartdoc class? (As I understand it has some static methods which use built-in generators - html and markdown.)

srawlins commented 2 years ago

No plans that I am aware of. https://github.com/dart-lang/dartdoc/issues/1667 is a request for a JSON output. https://github.com/dart-lang/dartdoc/issues/6 is a request for a machine-readable output.

The custom generation is not the most robust situation for generating something other than Markdown or HTML. For example, regardless of the templates used, Dartdoc will still generate HTML links inline, so an attempt at writing a PDF or LaTeX or something would still contain <a href= throughout.

EhsanAramide commented 2 years ago

So based on what you said, there is no solution to do that and do you have any solution for it? I think we have two solution to solve this

  1. Fork the repo and refactor as we need and implementing new generator and new form for generator usage
  2. Implement another one from scratch with dart analyser I don't agree with second one but it can be a solution. What is your opinion to solve this problem? (I will be happy for your response)
jcollins-g commented 2 years ago

I don't object to creating a new generator; if you can build a good general purpose one, we may even accept it as an external contribution, though I would want to see some design documentation for the proposal first I think?

If you implement a second one from scratch with the dart analyzer you may run into issues that we've already solved inside of dartdoc, but if your use case is very simple that can work.

jcollins-g commented 2 years ago

Since #1667 covers JSON output, I'll repurpose this bug as a more generic "support for custom generator plugins in dartdoc".

EhsanAramide commented 2 years ago

I don't object to creating a new generator....

No I don't create or write proposal this feature I just suggested my opinion about this topic and feature If I were able to do that I will response to team thanks for your response.🙌💙

EhsanAramide commented 2 years ago

Since #1667 covers ....

Actually I wanted to generate json for documentation of dart codes for search and do some works easier for machines but as I searched and reviewed source codes (in client-side of api.dart.dev, api.flutter.dev and pub.dev) I found some ways to get needed information as json from these servers . For example, in api.dart.dev the index.json path can help me or in api.flutter.dev the flutter/index.json and the pub.dev which provides full featured json apis. Thanks for your editing and response🙌💙.

Sreenu-Chandaka commented 1 month ago

unable to generate .md files using dartdoc plugin while trying to generate flutter project documentation. there are very limited resources available only. those not helped me at all. could you please any one give the solution for my issue.