cljs/site

docs integration

shaunlebron opened this issue · 1 comments

shaunlebron commented

Context: The pipeline for the cljs api docs handles a lot of complexity behind parsing/supplementing API data, and produces a plain data file (see its format here). This should be the only interface between the site and the docs.

Updating the docs should look like:

./update-docs.sh
./publish.sh

The update script should download and read the latest API docs file:
https://github.com/cljsinfo/cljs-api-docs/blob/catalog/cljs-api.edn

It should then generate files in site-jeykll/ after reading the latest docs:

auto-generated

The following files should be generated. All should have a comment at the top describing that it was created by the update script.

  • _data/docs/history.json (see data files in jekyll)
  • docs/<fullname>.md files for symbol pages, containing:
    • front matter such as symbol or namespace names
    • content blocks for markdown content (description and examples)
  • symbol references file for simple cross-referencing of symbols
  • doc-search-index.json available to JS for dynamic search sidebar

not generated

  • docs/history.md - this will render a history table and API changes by using the generated data in site.data.docs.history
  • _layouts/docs/symbol.md - symbol pages (set window.__cljs_api_doc__.symbol so sidebar knows what symbol we're in)
  • _layouts/docs/syntax.md - syntax pages are rendered slightly differently
  • docs/index.md - starting point, using the symbol layout.

sidebar

We need a sidebar for searching/exploring docs that will require some dynamic behavior.
This'll be a clojurescript React component.

On init:

  1. Check window.__cljs_api_doc__.symbol to set current symbol
  2. Check ?search= to set current query string for search term.
  3. Scroll the sidebar to accomodate current category, symbol, or search result.

Explore mode:

  1. display category column (highlight current), update current category on click.
  2. display symbols column (highlight current), navigate to symbol on click.

Search mode:

  1. if search field has anything, display results instead of category/symbol columns
  2. display results with highlighted matches
  3. each result link navigates to its symbol URL appended with ?search=
    • this allows the user to still see search results across pages
  4. Display a full search > link to navigate to a future page showing more details of each result
shaunlebron commented

gone a different direction. ditched jekyll, and will have to forgo search until later