Feature to add own set of docs

[zweicoder]

Would love to see this feature being added because I see devdocs as a central repository for all my documentation needs, and really want to be able to access informal docs (e.g. gists, custom reusable shell scripts, common set of git commands) from there :)

[gyamada619]

I second this suggestion.

[Thibaut]

DevDocs's format is standard across docs. The two main files are:

https://docs.devdocs.io/lodash/index.json
https://docs.devdocs.io/lodash/db.json

There are some requirements around the structure of HTML files + dependencies on CSS and JS, which I'm happy to try to formalize and make more flexible if there's enough interest in a public format.

This could then lead to an "add your own doc" feature.

If anyone is interested in this, the best way to go would be to make a proof of concept using the existing format and hacking the manifest file (docs.json) to make new docs show up in the app. I can then help improve and formalize all this.

[bapti]

@Thibaut this sounds like a great feature.

We've been playing around with devdocs at my workplace as a way of aggregating all of our documentation across all our different git repositories. It feels like there could be some kind of command line tool that builds out markdown into HTML that could then be consumed by devdocs?

[Thibaut]

We've been playing around with devdocs at my workplace as a way of aggregating all of our documentation across all our different git repositories.

Awesome. Would love to see how you did it and how we could improve DevDocs for this kind of use-case.

It feels like there could be some kind of command line tool that builds out markdown into HTML that could then be consumed by devdocs?

Sounds like a great idea, but unfortunately not something I have time to work on myself.

[uwufops]

There are some requirements around the structure of HTML files + dependencies on CSS and JS, which I'm happy to try to formalize and make more flexible if there's enough interest in a public format.

👍 It would be nice to have some description for this format, as quick guide and reference.

[Thibaut]

@yaruson what would you be using it for? Formalizing DevDocs's format is actually a big endeavor (need to consider long-term & backward compatibility), so I'd need to consider the cost/benefit vs. other features before working on it.

[uwufops]

@Thibaut I'm thinking about generating class reference documentation from object metadata (sources), and it might be better to produce ready-to-use index/db.json.

[jottr]

@Thibaut, I just looked into how to add a docset myself, but found it too cumbersome...
Have you looked at how Dash consumes docsets?
Since quite a few projects already tried to make their documentation work well with Dash, I suggest you don't duplicate efforts by creating your own format, but rather consume what is already there.

[Thibaut]

@jottr this would require a complete rewrite of DevDocs, because the way DevDocs works is fundamentally different from Dash. On DevDocs you don't browse the original docs in an iframe (with all the original CSS, JS, etc.); instead, the scrapers convert every doc into "normalized" HTML fragments, to provide a fast and consistent reading experience inside the app (no iframes, offline mode, etc.).

This approach has the downside of requiring more work upfront (to add docs), but provides a much better UX, which, for better or for worse, has always been my priority with this project (quality > quantity).

[kaos]

As a user that have deployed devdocs inhouse for our own documentation needs, I say that the scrapers are pretty straight forward, once you get to know them.

What I was (am) missing is better integration for managing the stored/generated documentation. It is something we could look into, but I took the easy way out, and simply rebuild a docker image that is deployed together with the devdocs image to mount in the compiled docs. It's a bit rough, but it works.

[Thibaut]

@kaos if you have any suggestions for making the scrapers easier to write and manage, let me know (in a new issue).

[fireundubh]

@Thibaut Is there any reference material on manually creating documentation to be added to DevDocs, as opposed to using the scraper - or perhaps for scraping?

[Thibaut]

@fireundubh Unfortunately not, but the file format is pretty straightforward. See #295 (comment).

Here's an example of a scraper that manually generates files instead of scraping: https://github.com/Thibaut/devdocs/blob/master/lib/docs/scrapers/support_tables.rb

[voronoipotato]

Microsoft uses markdown for their docs, for example https://github.com/dotnet/docs/tree/main/docs/fsharp/language-reference . It's not clear from the documentation though if I can scrape markdown, or if I will need to convert it into a website and then scrape that? Also is there a way I can import them on devdocs.io? I saw an import button in the settings but it appears that was just for importing the settings? Can't we just use a markdown.js to render the markdown?