Closed ozum closed 2 months ago
Today, I published concat-md for creating single file from multiple markdown files. Although it is not typedoc-plugin-markdown
specific, I developed it primarily to use with typedoc-plugin-markdown
.
It does not simply concat files, it adds necessary titles, and changes level of existing titles.
$ typedoc --plugin typedoc-plugin-markdown --mode file --out docs
$ npx concat-md --decrease-title-levels --dir-name-as-title docs > README.md
Above command;
This is an initial release, but I think it is OK to be used in projects.
@tgreyuk, I will appreciate if you can give it a try and provide some feedback.
@ozum this looks pretty cool. sorry been a bit busy on some other stuff but I will test this out properly when i have a bit of time.
@ozum I'm loving my new autogenerated API documentation - thanks!
@tgreyuk, thanks.
Also thanks to suggestion of @Vinnl, concat-md
now converts links too.
@tgreyuk, I also appreciate if you mention md-concat
in README with an example if you find it useful for typedoc-plugin-markdown
.
Any news about this? I really dislike writing READMEs, mainly because I JsDoc my code already and I hate to copy the stuff there to the README, and having to manually update the README is a pain for me.
I would like to just have a template README, write some specific texts, and everything else would be filled automagically, so I could just focus on what I like, that is coding.
Another current issue I am having, is the same as the https://github.com/tgreyuk/typedoc-plugin-markdown/issues/109. typedoc-plugin-markdown seems good, but the generated .md isn't really good to be used in a README as it takes too much space. My package is a React component, and I just want a table with the properties of the component. It's just ~10 props, but for me is already a mental pain having to copy/paste and having to maintain it through the time, specially because I have ~8 npm packages (not popular at all) and I plan to have many more, as I really like to do it.
I thought of creating from scratch basically another TypeDoc to do what I want using AST, but that would take more time that I am willing to spend on it. Seems to be a better option to use this package and do some transformations to achieve what I want. For now, I will write a quick .js to convert the generated .md to a table.
I already have a template generator for my projects that also creates a basic README. I just need that automatic README content filler so I can really automate my production line.
@SrBrahma Thanks .. makes sense - I have been meaning to have a look at tabulating interface props for a while. Currently refactoring a few things which will make it easier to incorporate this. Will report back in due course.
Thanks for the quick answer! I will as soon as I do my quick toTable.js post it here as it may help you or at least give you some ideas. I think I will just use regex to get the info I want from the .md.
Done!! Probably it's just a dirty workaround that won't work on other cases that includes other JSDoc tags. In the entry file, differently from the original code typings, I made a prop required and other without the default tag, to handle and test different cases.
<!-- DO NOT EDIT README.md (It will be overridden by README.hbs) --> # {{changeCase "title" (package "name")}} <!-- Badges from shield.io --> > {{package "description"}} > > {{#each (package "shields")}}[![{{this.name}}][{{this.name}}]][{{this.name}}-url]{{/each}} {{#each (package "shields")}} [{{this.name}}]: {{this.image}} [{{this.name}}-url]: {{this.url}} {{/each}} <!-- START doctoc --> <!-- END doctoc --> Some manual content I want to include in my README. Below main part is added by jsdoc2md # API {{>main~}}
@tgreyuk using that handlebars system, I made https://github.com/SrBrahma/react-native-shadow-2/tree/wip/resources/README. My handlebars only populates the {{shadowProperties}}
table for now. Maybe we could make a typedoc2readme
or typedoc2md
? Writing for eg {{table interface@shadowi}}
would get docs/interfaces/shadowi.md
content, transform it into a table, and populate the corresponding field in .hbs. I don't know about jsdoc2md, maybe we could use its same syntax and maybe some of its parsers or do it as we like.
I am interested in doing it. In fact, my proof of concept is already done in that link, it would just require some further generalizations for a basic and useful release version. I don't think it would be possible a fully automatic README as it would probably get really messy, but using handlebars and typedocs automations would simplify and make the maintenance and the development of projects way easier.
Do you have any interest on it?
jsdoc2md
optionally produce single markdown page from multiple modules/files by concatenating them. Also let developer use a handlebars template for that single page.This is super useful to generate a README.md file for npm and github from code automatically.
Below is a simplified example handlebars template I use for that purpose:
All those can be achieved programmatically with
typedoc-plugin-markdown
too, but it is helpful to have this feature built-in, because npm & githubREADME.md
file generation may be used by lots of people.EDIT:
Why this is useful?
Sometimes, especially for small modules, it's enough to have a single README.md file for the whole documentation, and there is no need to have extra web sites/github pages or wiki pages. For example: