Would it be useful/possible to support document-format such as the gem called fpm uses? See: https://fpm.readthedocs.io/en/latest/

[rubyFeedback]

Hey Loren (and everyone else),

The fpm gem has quite nice documentation at:

https://fpm.readthedocs.io/en/latest/

What I like about it is mostly the structure/layout/content there.

Now, rubygems.org has lots of different gems hosted, and we can use a .md file there, which works fine. I use that since some years.

However had, my larger gems are beginning to actually have a LOT of documentation. For example, yesterday I counted, and one of my "top 3" biggest gems now has more than 5000 lines of code. This becomes a bit difficult to navigate all in a single .md file, even more so in display (which is the fault of rubygems.org of course, nobody else; but I assume most people don't have that long a documentation).

Anyway - this was actually not the point I wanted to ask or propose; it just serves as intro.

I do know way too little to understand how to create high quality documentation such as for the fpm gem - but I wondered whether we could use/combine rdoc, yard etc... to also be able to offer high quality documentation? This is of course probably not due to any single person alone (would be quite some work), but perhaps we could get things going in the long run for that - if enough people may wish to have something like this.

So I think this is actually two questions, perhaps to you primarily, perhaps to everyone - please do feel free to close this issue at any moment in time, I don't want to add to any burden of additional work (I understand time constraints):

1. Would you actually think that being able to have documentation "in style" similar to the example above, such as for fpm, would be useful to have, or would this perhaps be a feature that not many people may use? (This can also be the case ... if only 0.05% of gem devs ever make use of it then I think adding support for that is not worth it).

2. Do you think it could be added, as support, for the existing ruby-doc ecosystem? As I wrote above I don't know how the docs are generated exactly on what fpm did, but I suppose perhaps it may purely be a hosting issue, rather than a text-generation issue (I know rdoc and yard generate documentation... no clue whether the thing fpm uses also does generate documentation. Perhaps they use some template from which they generate something like these documents).

Cheers, Robert

[MSP-Greg]

YARD's main function is creating html documents whose content is based on an app's source code and the comments associated with it, along with a UI to navigate them.

The example you cited, https://fpm.readthedocs.io/en/latest/, shows a system that assembles documents.

Two very different things.

[lsegal]

YARD actually supports readthedocs style rst documentation via "Guide style documentation":

https://github.com/lsegal/yard/blob/master/docs/WhatsNew.md#added-new--t-guide-template-for-guide-based-docs-070

You can see this in YARD source:

git clone git://github.com/lsegal/yard
cd yard
ruby bin/yard doc --yardopts .yardopts_guide
open doc_guide/index.html

[sandstrom]

I'm doing some issue gardening 🌱🌿 🌷 and came upon this issue. It seems outdated, with no activity for 3 years.

By closing some old issues we reduce the list of open issues to a more manageable set. Let me know if you think this is a mistake and that the issue should stay open.

To maintainers

Open the 'Discussions' tab on the repo. That way, much of what's in issues today can be easily moved to Discussions (there will be a dedicated button on each issue, after it's enabled).