Repository navigation
Feature to add own set of docs #295
Description
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 :)
Activity
gyamada619 commentedon Dec 4, 2015
I second this suggestion.
Thibaut commentedon Dec 13, 2015
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 commentedon Feb 25, 2016
@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 commentedon Feb 25, 2016
Awesome. Would love to see how you did it and how we could improve DevDocs for this kind of use-case.
Sounds like a great idea, but unfortunately not something I have time to work on myself.
0x464F58 commentedon Mar 3, 2016
👍 It would be nice to have some description for this format, as quick guide and reference.
Thibaut commentedon Mar 6, 2016
@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.
0x464F58 commentedon Mar 7, 2016
@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 commentedon Jul 14, 2017
@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 commentedon Jul 14, 2017
@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 commentedon Jul 24, 2017
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 commentedon Jul 29, 2017
@kaos if you have any suggestions for making the scrapers easier to write and manage, let me know (in a new issue).
fireundubh commentedon Feb 25, 2018
@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 commentedon Mar 24, 2018
@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 commentedon Sep 21, 2022
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?
VEER-TANMAY-SACHIN commentedon Jun 22, 2024
Do we have a tut for adding new doc. @Thibaut
yes i have read the .md.
its bit difficult to understand.
simon04 commentedon Sep 14, 2026
We now have a "import" button thanks to #2733 on https://devdocs.io/offline.