New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

How do we manage to bundle the documentation of all plugins into a Biogems website? #10

Closed
wilzbach opened this Issue Aug 1, 2014 · 3 comments

Comments

2 participants
@wilzbach
Member

wilzbach commented Aug 1, 2014

Following Max's advice I thought I just create issue for every open questions, so that is is easier to track things.

Bruno: I'm a fan of having literate code and using docco. I think it's a good practice to write the comments as docs when you're writing the code, and that way you don't have to figure out where the documentation is.
However, this isn't of course an alternative to a global API doc. As I mentioned, some projects do global APIs manually, like underscore, express, nodejs and socket.io. However, something automatic would be better. I'm currently exploring doxx as it seems to be able to generate a single doc for multiple modules. If doxx can solve most of the problem, we can then tweak it to generate an output with some of Biogems features.

@wilzbach

This comment has been minimized.

Member

wilzbach commented Aug 6, 2014

We are very happy that we are building an open registry for bio npm packages.

For documentation we agreed for the moment that the Readme.md is the simplest common denominator. On our registry you will just get an extra badge for an existing ReadMe and also for external documentation like jsdoc.

However what we want to achieve are visually appealing snippets for components.

For more info (draft!) how a visulization component could specify those specs have a look here:

https://github.com/greenify/biojs-sniper

@wilzbach

This comment has been minimized.

Member

wilzbach commented Sep 11, 2014

At the moment we just parse the README.md of every npm package and display it on the bottom of every detail page.

http://registry.biojs.net/client/#/detail/biojs-io-clustal

Suggestions / Ideas are highly welcome.

@bmpvieira

This comment has been minimized.

Member

bmpvieira commented Apr 4, 2015

Sounds good, displaying the README.md in the registry is what NPM is also doing and seems to be the simplest solution. As for combining all the docs into a global API, I'm just concatenating the docco html (with some tweaks) for doc.bionode.io, but this could be improved.
I'm closing this as the documentation in the BioJS registry issue seems solved. As for global documentation, we can continue at #27

@bmpvieira bmpvieira closed this Apr 4, 2015

@bmpvieira bmpvieira self-assigned this Apr 5, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment