Documentation

[attie]

I am planning to spend time writing more documentation for Glasgow, in preparation for the influx of new users via Crowd Supply.

I'm sharing my plans here, please feel free to comment with suggestions.
This will reside in the /docs/ directory, and will not likely touch README.md, at least for now... it may absorb some of the content at some point.
Some of these items will draw heavily on existing words.

The longer-term goal of this issue is to also produce static HTML that is hosted somewhere (probably using GitHub pages on a branch of this repo?)

• Index
  • Intro - what is Glasgow & what can it do?
  • Project overview
    • Revisions & naming
• Getting started
  • Installation
    • Linux
      • Ubuntu 20.04 LTS
    • macOS
    • Windows
  • Running / invocation
    • Overview
    • Basic run Examples
    • REPL & Script usage
    • Built-in Analyzer
  • Common problems & resolutions
• Applets
  • Overview
  • Details
  • Out-of-tree applets (TBD...)
  • My first applet example / template / walkthrough
• Hardware variants
  • Naming scheme
  • foreach
    • Feature summary
    • Board overview
• Production
  • PCBs, BOM & Assembly
  • Provisioning (serial numbers & firmware)
  • Testing
• Internals
  • Boot
  • Communication (between FPGA and Python)
  • Applet build, load & run
  • probably much more, TBD...
• Q&A
  • Where did the name come from?
  • Where can I get one?
  • Where can I ask for help?
  • Where & how can I use it? (Licensing)

[whitequark]

Sounds wonderful! Let's gather on our IRC/Discord channel to discuss this sometime soon?

[whitequark]

• Add instructions for Ubuntu 20.04 LTS

These are really annoying--I've had a go and I think I won't be working on them.

#422 (comment) includes a Docker-based reproducer, which will come in handy for anyone daring enough to try.