Skip to content

Latest commit

 

History

History
68 lines (60 loc) · 4.71 KB

Roadmap.md

File metadata and controls

68 lines (60 loc) · 4.71 KB

Things still to be implemented

  • Interactive code samples!
    • First pass - include the compiled javascript for code samples so you can see the result
    • Second pass - make the code samples editable, with an in-page compiler so you can experiment
  • Parse the bsconfig.json and package.json of a project
  • Handle ocamldoc (see included octavius source) so we can build ocamly projects too
  • Support crowdin translations
  • Support docs versioning -- hang on to older versions & provide links to them
  • Better tokenization, split camel-cased words up to tokenize separately

itemized work to do

  • "edit" on readme doesn't go to the right place (docs/index.md)
  • accept cli args
  • highlighting in code blocks + hover-for-type
  • argument-level documentation (refmt doesn't parse this properly :/)
  • topologically sort the items in the sidebar - or just allow you to specify order
  • allow embedding of the docs for another module in a markdown page / module docs
  • add cli options for debug, verbose mode, etc.
  • add meta tag cards for social media sharing
  • respect @deprecated (and other things?)
  • aliases - only show the last item of a type path (full on hover)
    • if the last item is "t", then also show the parent
  • A sidebar!
    • a table of contents
    • listing of other modules in this package
    • highlight the currently selected thing in the sidebar. scroll-tracking
  • have an "edit this file" link on the page
  • make sure mobile looks nice
  • make it easy to build for a whole project
  • collapse top thing when on mobile
  • also process normal markdown files, and add them to the sidebar.
  • Integrated search! see this example (powered by this rust code and this js code)
    • will pre-create an elasticlunr index, and load it up when the user selects the search field
    • include the markdown files in the index
    • maybe allow you to indicate that there are other indexes (e.g. for other libraries) that you'd like to load? So reason's docs could load reasonreact for better cross-searching
  • inline interactive code samples!
    • make them editable! This may require some gymnastics, but I'm confident pack.re can pull it off.
    • on mobile, dont have them be editable. Have a run link that will take you to the playground with the code pre-filled.
    • I'll want a way to specify a "wrapper" for the code, e.g. if it's "in a reprocessing draw function"
    • also specify that the code should have a canvas created adjacent to it?
    • the default should probably be "run in a web worker", but you can override to write to a canvas or similar
    • probably want to lazy-load codemirror, the bucklescript compiler, etc. to be easy on the perf.
    • don't auto-eval, probably. When you click on a codeblock, you can click "run", and then run it. At that point, we'll load the bucklescript compiler? Although maybe we'll include a precompiled version of each inline script because why not.
  • Handle markdown files just fine. Include them in the sidebar, process them in a similar way (including allowing interactive inline code samples!). The only difference is there will be no declared items.
  • have a zero-config "run this @ the project root and do everyting" mode.
  • integrate into redex, such that it creates documentation for literally everything.

Thoughts on gitbook-like functionality

Crawl ./docs looking for markdown files. If there's an index.md, that's the main page. Otherwise, we use Readme.md. The main file is always listed at the top in directory listings.

For all other files:

  • if a file or directory is prefixed with \d_, then that number will be its index in the listing
  • files also do the index.md or readme.md thing (maybe readme.md in the folder as well, for better github browsing?)
  • code blocks are magic'd to be editable & evaluable
  • links to other pages should work, including to api docs things.
    • you can do an absolute link, and it will work out the relative link, so that if the files are hosted not at the root it will be ok
  • should the api docs be placed in ./docs/api? Maybe. Probably.
  • maybe allow you to @doc include bits of docs from the api? That could be fun.
  • probably want to allow "splat"ing in code from different places. Like example code, etc.