search

ReactiveX / rxjs

A reactive programming library for JavaScript
https://rxjs.dev
Apache License 2.0
30.78k stars 3k forks source link

Move to just using Markdown docs (ala RxJS 4)? #851

Closed benlesh closed 8 years ago

benlesh commented 8 years ago

So, I find the documentation generation problematic.

Doc Gen (esdoc, et al)

PROS:

  1. It maintains links between the source and the docs.
  2. Inline docs can be helpful.
  3. It's easier to remember to update docs when they're right next to the code your changing.

CONS:

  1. it's really that much prettier/readable than markdown
  2. it's not always straightforward to create just want you want to document.
  3. I'd like a lot more detail in the docs.
  4. More painful to link docs that are external to what's being generated.

    Markdown Docs

PROS:

  1. @Widdershin's sweet tool can be run on the code inside of the docs
  2. Much easier to get readable format and add lots of data/value without junking up source code
  3. We might be able to straight port some of the RxJS 4 docs
  4. Can more cleanly add in linked documentation that doesn't directly relate to source code. (how-tos, etc)

CONS:

  1. Keeping links between docs and source becomes more difficult
  2. Keeping them updated with code changes can be problematic because they're not next to the code. Out of sight, out of mind.
  3. Doesn't have fancy searching functionality built in, really. There's GitHub search, but that's not quite the same.
staltz commented 8 years ago

I'm pretty optimistic about esdoc. In general I'm favorable of putting technical specs of each operator in esdoc, and then elaborating in more details at reactivex.io where we can put documentation not linked directly to source code.

benlesh commented 8 years ago

then elaborating in more details at reactivex.io where we can put documentation not linked directly to source code.

That's totally true. I'd lost sight of that when I made this issue. (I'm not sure why it's come up at Netflix a dozen times)

Widdershin commented 8 years ago

As I mentioned in the original markdown-doctest pull request, if we do opt for esdoc as the future, I will write almost definitely write esdoctest if nothing does that already, as I think having runnable examples as a CI enforced concept is quite important.

Don't let markdown-doctest sway you too much is all I'm saying.

Widdershin commented 8 years ago

Have any examples been written using esdoc so far? Would love to be pointed in the right direction if so.

staltz commented 8 years ago

I will write almost definitely write esdoctest if nothing does that already, as I think having runnable examples as a CI enforced concept is quite important.

That would be great!

h13i32maru commented 8 years ago

Hi! I am developing ESDoc. Thanks for using it :smile:

ESDoc supports to integrate markdown file into documentation. Please see https://esdoc.org/feature.html#integration-manual for more information. this might help to you.

If you have feature requests for ESDoc, please tell me it.

Feel free this comment. Thanks.

staltz commented 8 years ago

ESDoc supports to integrate markdown file into documentation. Please see https://esdoc.org/feature.html#integration-manual for more information. this might help to you.

Perfect, then.

benlesh commented 8 years ago

I think I'm 90% ready to close this issue... But how much description can we add in ESDoc? Can we embed little JSBins or anything like that?

staltz commented 8 years ago

Can we embed little JSBins or anything like that?

Can't even do that in markdown docs. :D ESDoc might be possible since it generates a webpage.

benlesh commented 8 years ago

Can't even do that in markdown docs. :D

I know you can't do this in comments, but this is true for .md files committed to the repo as well? Aww, man... 😕

staltz commented 8 years ago

E.g. I know you can't embed youtube videos in .md files, but you can embed images and gifs.

Widdershin commented 8 years ago

If we're going to do markdown + esdoc and there's a build step to compile to html, I feel like we can totally do interactive examples. The code for extracting code snippets already exists in markdown-doctest, we would just need to browserify the code and embed an editor in the generated htnl.

I might take a crack at that soon, see what's possible On 4/12/2015 9:22 am, "Ben Lesh" notifications@github.com wrote:

Can't even do that in markdown docs. :D

I know you can't do this in comments, but this is true for .md files committed to the repo as well? Aww, man... 😕

— Reply to this email directly or view it on GitHub https://github.com/ReactiveX/RxJS/issues/851#issuecomment-161771801.

benlesh commented 8 years ago

@Widdershin just blew my mind a little there. That sounds really cool

I think we can close this issue and stick with esdocs for now then.