Normalize project-development.md TOC

[srid]

• make the TOC in sync with actual headers
  • thereby introducing missing headers in the TOC
• group cabal/ghc building sections under "Development"
  • intention is to group stuff related to development (as opposed to
    building/deployment) under a separate heading.
  • eventually editor setup docs will belong to this section
• change markdown header style (allows h3+)

The TOC is auto-generated in Emacs using
https://github.com/ardumont/markdown-toc (which is part of the Spacemacs
markdown layer)

/cc @ElvishJerricco - thoughts? I wanted to do this before opening a PR for emacs / spacemacs setup docs.

[srid]

Preview: https://github.com/srid/reflex-platform/blob/project-docs-toc/docs/project-development.md

[ryantrinkle]

@srid Any way to make this accessible to non-emacs-users? Is there a way to run emacs headless and do nothing but update a single doc? I don't want to exclude users of other editors.

[3noch]

Yeah I've used haskero/intero in the past to great effect. It's just sluggish but on a fast enough computer I'm sure it would be fine.

[srid]

@ryantrinkle

Any way to make this accessible to non-emacs-users?

Yes, pandoc has a way to generate TOC. Not very straightforward at first glance, but probably better than running emacs headless.

[srid]

@3noch Intero works? I thought it required stack.

[srid]

@ryantrinkle ^^ TOC now uses pandoc.

By the way, why is project-development.md not part of http://docs.reflex-frp.org/en/latest/ ? cf. reflex-frp/reflex-frp.org#1

[ryantrinkle]

@srid Awesome; pandoc sounds good. One last thing, though: rather than asking people to have pandoc installed, I think it would be good if we had a script in reflex-platform that used nix to get pandoc (and anything else it might need) and ran it. @alexfmpe might have some thoughts on the best way to do that.

[3noch]

@srid Yes it does require stack but stack can just piggy back on nix-shell underneath.

[ElvishJerricco]

@ryantrinkle I think I did something like that in that other PR of mine with the auto-generated docs. https://github.com/reflex-frp/reflex-platform/pull/225/files#diff-0036526467bb681c09a456799fcac425 & https://github.com/reflex-frp/reflex-platform/pull/225/files#diff-4592fe66ef882f1bce7c73626ae3116b

I think this is a fine change. But I think it accentuates the need for auto-generated docs to be put somewhere. It'd be nice if we didn't check the ToC in, and instead just applied pandoc --toc in the deployment process. Eventually, this doc, and the per-option docs in #225 should be auto-generated and deployed.

[srid]

@ElvishJerricco It'd be nice if we didn't check the ToC in, and instead just applied pandoc --toc in the deployment process.

Interesting. This approach dovetails into something I've been thinking of today--unifying our doc sources in one common place. Currently we have

• docs.reflex-frp.org .rst files
• reflex-platform README.md
• project-development.md
• QuickRef.md from reflex and reflex-dom
• etc.

Ryan stressed the importance of keeping the doc sources in the git repo to have PRs update the docs as part of the contribution process. So whatever generator/ deployer thing we have could read the sources from disparate git repos (pinned in reflex-platform), generate TOC and create a nice navigatable website out of it ... which can perhaps be served by reflex-frp.org ... thoughts?

[alexfmpe]

So whatever generator/ deployer thing we have could read the sources from disparate git repos (pinned in reflex-platform), generate TOC

I like how that sounds.
If we get some flow where reflex-platform/develop auto-bumps every time reflex or reflex-dom commit to their develop branch, this would make reflex-platform/develop always be up-to-date doc-wise through the child repos.

[alexfmpe]

I wasn't too giddy about having auto-generated docs because that could take away from the simplicity of going into a repo for the first time and immediatelly having lots of info right away in the README.md, only a pagedown away.
Whatever merit there would be in auto-generating TOC/headers/formatting/whatever, wouldn't be applied to the original source back in the repo.
Then again, given that even crazier stuff like https://github.com/def-/gifstream exists, I guess we could try to aim for the best of both worlds.

[ElvishJerricco]

Yea I think we should aggregate all the docs from however many places (hopefully including Haddocks for Reflex and its dependencies) and publish them somewhere, with a big message at the top of the README in reflex-platform pointing at the site. In principle, none of this is particularly hard to do. The only unsolved part IMO is getting some kind of auto-deployment of docs.

[ali-abrar]

Is the TOC work in this PR ready to merge, or are there still changes to be made?

Perhaps some of the other suggestions should be (or are?) separate issues.

[srid]

Is the TOC work in this PR ready to merge, or are there still changes to be made?

I think the main thing left to do is to add pandoc to reflex-platform.

Perhaps some of the other suggestions should be (or are?) separate issues.

Or even a project of its own (The Grand Reflex Website).

[3noch]

Let's do something like #670 instead.