Rework project documentation

[jeanthom]

The README was starting to get a bit bloated, so I reworked the project documentation splitting the information into multiple files.

https://github.com/jeanthom/openFPGALoader/tree/doc-rework

[hhirtz]

This really helps out newcomers. Thanks a lot for reworking the documentation.

Just a small typo though

[umarcor]

This is really nice! It's so close from building an static web site:

• Add a configuration file.
• Add a frontmatter to each markdown source.
• Build the site in CI and push it to branch gh-pages.
• Advertise trabucayre.github.io/openFPGALoader as the documentation site.

I can help with that!

There are several tools for generating static websites from text/markup sources (dbhi.github.io/mdpaper). Since this PR contains all markdown sources already, I recommend using Hugo. I am familiar with it because that's the tool used in hdl.github.io/awesome and vhdl.github.io/news. There are hundreds of themes to choose from: https://themes.gohugo.io/. Therefore, I would need someone else to decide which to use.

Alternatively, most of the open source EDA projects do use Sphinx instead of markdown based static site generators. That's the case of SymbiFlow, GHDL, VUnit, pyVHDLModel/pyVHDLParser, cocotb, TerosHDL, Boolector, edalize/fusesoc, wishbone (FOSSi), SpinalHDL, tsfpga, etc. Sphinx provides an interesting feature named intersphinx which allows cross-referencing content across sites, as if they were local references. That is really handy for building knowledge as a community. For instance, a few hours ago, I proposed in f4pga/f4pga-arch-defs#2240 to have some content written in this repo instead of there. Therefore, it might be worth doing some effort from converting markdown sources to restructuredtext.

Strictly, Sphinx can import markdown sources, so it is possible to start using Sphinx straightaway, and ignore Hugo/Jekyll/others. However, when using markdown in Sphinx several features related to (cross-)references are not available. That's why it's desirable to use rst instead of md in the mid term.

@jeanthom, I'm not proposing you to take care of these further enhancements. I think this PR is ok as-is. However, I believe it is pertinent to discuss it here.

[trabucayre]

Thanks for this big rework, this is now a more clear documentation. LGTM.

I'm agree with @umarcor this is a good starting point to create a static site with more details about internal structure.

I have just an hesitation about README.md: it's maybe required to add basic commands to have a first synthetic page with bare minimal informations to use openFPGALoader. It's the same question with board's table, this is used to provides board's keyword. But of course I'm maybe wrong.
Thanks again

[umarcor]

Moved to #105.

[hhirtz]

Going back to the topic,

it's maybe required to add basic commands to have a first synthetic page with bare minimal informations to use openFPGALoader

These are covered in the "First steps" document (link is at the top of the README), though I agree it could be better placed (you want to know what the program is before going through first steps, installation etc).

IMO, instead of just the Usage section, having something like this would be clearer:

# Install

Installation instructions are available for [Linux](INSTALL.md#linux), [Windows](INSTALL.md#windows) and [macOS](INSTALL.md#macos).

# Usage

- [Basic usage](doc/first-steps.md)
- [Troubleshooting](doc/troubleshooting.md)
- [Advanced usage](doc/advanced-usage.md)

<keep the "openFPGALoader --help" block below>

[jeanthom]

Hi everyone,

Thanks @umarcor for moving the hdl/constraints discussion into its own issue. I think it will have a better visibility than here, where it'll get eventually closed.

Maybe we could also create an issue to discuss the creation of a web page too? I guess we'll have lots of discussions about how to implement it 👍

@trabucayre I tried to implement the changes you requested, tell me how you feel about it

[trabucayre]

LGTM.
Some information in Advanced usage are maybe required in a first page to have a big picture.
I hesitate between applying this PR directly and update some small part in a second time.

[trabucayre]

Applied! Thanks