Suggestion of structure for docs

[numero-744]

The goal is to both:

• Make it easier for all people discovering SpinalHDL (knowing VHDL and Verilog might help but it is not a requirement)
• Make it easier for people to find information

---

Root:

• short description
• short motivation
• where to find docs

1. Introduction
   1. About SpinalHDL
      1. What is SpinalHDL?
      2. The Spinal flow
      3. Advantages of using SpinalHDL over VHDL and Verilog
   2. A simple example (from the template)
      1. Component
      2. Ports
      3. Internal logic
   3. Projects using SpinalHDL
   4. Getting in touch
   5. License
   6. Contributing
   7. FAQ
   8. More learning materials (add cheatsheets)
      1. Help for people coming from VHDL
2. Getting Started
   1. Install and setup
   2. Using spinal from *
   3. A simple guided exercise
      1. Writing the logic step by step
      2. Writing the test step by step (with only assignments sleep, also mention requirements and how to generate code if no compatible simulator)
      3. Running the test and open the waves in Gtkwave
      4. Congratulations! page
3. Common hardware description concepts
   1. Notion of comb and seq logic (mention a few design errors)
   2. Data types & basic operators, literals
   3. Rules / conditions / muxing (+ setWhen/clearWhen + a few design errors)
   4. Component (+ interface, directions, how to instantiate)
   5. Comments (Huh, fast part)
   6. Areas (preview of clockdomains)
4. Compound types (Bundle and Vec)
5. Enumerated types (& encoding)
6. Configuring generation (SpinalConfig)
7. Blackboxing
8. Managing growing projects (with package and import)
9. More simulation facilities
   1. Simulation time vs hardware (types, syntax equivalent constructs at elaboration time/hardware/sim #145 + read & write into hardware)
   2. Interacting with a clockdomain
   3. Random tests
   4. Control flow and functions (like before but focusing on simulation)
10. Common hardware generation concepts
    1. Elaboration-time vs hardware (types, syntax equivalent constructs at elaboration time/hardware/sim #145)
    2. Component parameters
    3. Creating a configuration
    4. Elaboration-time control flow (if, for, also mention null and mutability)
    5. Functions (+ when an Area should be created)
    6. Pre-conditions (require)
11. The standard library
    1. Interconnections
       1. Flow
       2. Stream
       3. Fragment
    2. Buses
    3. Logic
       1. State machine
    4. Peripheral
       5. UART
    5. TODO other things
12. Writing better code
    1. Style guidelines
    2. Idioms (Add section for idioms #131)
13. At least one harder / less guided project for exercise (TODO)
14. Helper scripts
    1. HTML test report generation (easy, just sbt config) + XML parser to match test list with spec if I have time (spoiler: I won't, unless my manager tells me to, and he is quite interested)
    2. Ubuntu full-flow installer (for teaching)
    3. Use one GTKWave config with several wave files
    4. GTKWave user configuration example
15. More advanced stuff
    1. Clock domains
    2. Assertions
    3. Report
    4. RAM/ROM
    5. Analog and inout
    6. Details about simulation
    7. Formal verification
    8. Scope property
    9. Interaction with Scala
16. Examples
17. Appendix
    1. All other, more formal, contents
    2. Design errors

---

I would like "developers area" (about internals I guess) to be apart, because when searching things sometimes it appears first…
An idea could be to manage master and dev in parallel: dev has this and master doesn't.
Pushing/merging into master automatically opens a PR from master to dev, and contributions to this section are PR'd to dev.
Or maybe even two separate branches with completely different contents.

For reference, structure is inspired from: https://doc.rust-lang.org/stable/book/

[numero-744]

I think that "More simulation facilities" would go before "Common hardware generation concepts" because it will not be a full course about verification, and these simulation facilities will be really useful to simulate things, including the stuff of "hardware generation concept". So I would swap those two parts.

[Readon]

Do you think it's better to describe things as sections below:

Working flow

...

Elaborate Stage

• if else
• for
• SpinalConfig
• ...

Hardware Description

• Comb Logic
• when
• switch
• design errors

Verify Stage

• Simulation
• Formal Verification

Standard Library

Interconnection

• Flow
• Stream

Bus

• Axi4
• Wishbone

Peripheral

• UART

Although, this would make a deep tree, or we can use this definition constantly.

[numero-744]

IMO this structure is clear for us as we already know Scala, Spinal and how they relate to each other. This theory-first approach is okay too for students. But it wouldn't be really helpful for hardware designers discovering SpinalHDL, who know VHDL and/or Verilog, a little bit of C just to write tests to run in a CPU in simulation and copy-pasting tcl and tcsh commands around to run simulations and have an idea of the number of gates used by their IP in synthesis, without knowing any other programming language. For them it is not really practical and fun to learn, not enough practice-first. I think putting Elaborate stage before Hardware description is really Scala/software-oriented so not practical for people wanting to learn describing hardware using SpinalHDL and not knowing Scala and programming languages in general. It is putting more advanced things (how to generate) before simple things (structuring, inputs, outputs, comb logic, seq logic); how to make your component generic before leaning how to create a simple component. Putting Simulation at the end is not practical and fun because they won't be able to practice things, to see how what they write behaves as they write it. For design errors I think it is good to put them in hardware description as they will likely encounter them there ^^' What about introducing them as long as they can encounter them with the notions they learn (eg: mention latch in when section) and keeping the full descriptions and workarounds/tags as we currently have them in a later section? I like this more fine-grained way to split things in the library, I'll update the issue description; thanks! Le 21 novembre 2022 02:31:12 UTC, Readon ***@***.***> a écrit :

…

Do you think it's better to describe things as sections below: ### Working flow ... #### Elaborate Stage - if else - for - SpinalConfig - ... #### Hardware Description - Comb Logic - when - switch - design errors #### Verify Stage - Simulation - Formal Verification ### Standard Library #### Interconnection - Flow - Stream #### Bus - Axi4 - Wishbone #### Peripheral - UART Although, this would make a deep tree, or we can use this definition constantly. -- Reply to this email directly or view it on GitHub: #151 (comment) You are receiving this because you were assigned. Message ID: ***@***.***>

[Dolu1990]

Fondamentaly, we can have both, both aproache fit different situations.

[numero-744]

Having two parallel tables of contents?

[wifasoi]

As long there is not a table of table of contents

[numero-744]

Unless arguments against the suggested (updated) structure or example cases where it does not fit are provided, and unless it is shown that no modifications can be provided to have one structure matching all cases, I don't think it is a good thing to duplicate docs.

[Dolu1990]

I would not count it as duplication, as they are different perspective, as poeple which know well VHDL / Verilog will have very different expectation than people discovering hardware design.
But fondamentaly, the way you propose (numero-744) should be the default one i think.

[numero-744]

So I suggest to first go for this structure, and with the result see if something else should be added for other cases

[Dolu1990]

fine to me ^^

[numero-744]

TODO: move developer area to branch dev-area, keep empty section to point to it and add link into CONTRIBUTING.md to it. Default branch becomes dev and master points to the most recent tag.

[numero-744]

Update of the structure above:

I plan to introduce design errors as the user learns to do things that could trigger them so the more "formal" definitions can go in the appendices.

I add a section for "helper scripts", which could be a collection of scripts (and other text files in general) that can be useful in some / many situations.

---

Current status of this issue:

I'm starting my PhD so expect me to spend less time on SpinalHDL (coming back to SystemVerilog will hurt 😅). I won't PR for this issue until 1.8 is released (there are few PRs to merge before that 🤞), then I should PR again (my Spinal priorities will be this and the template).

---

Developer area contains stuff that is not needed my most users so it is planned to put that into a new branch (developper-area for instance) so that it is still accessible online thanks to sphinx-multiversion without being put in search results of users, who don't want that.

Also, we can have master branch for published features, but to also have a dev branch to document unpublished features merged into the code dev branch.

• In GitHub the default branch would be dev (so that PRs go on this by default)
• On the published pages the default branch would be master (for most users)
• Maintainers can edit PRs so that they point to master if it is about a documented feature.
• Merging in master would imply by a GH workflow rule merging master in dev to keep it up-to-date.

@andreasWallner what do you think about this, would it be an issue with the tests you are setting-up in the RTD repository?

[andreasWallner]

@numero-744 I think for the RTD code it's not an issue.

About the idea of moving part of the documentation to another branch: I don't think this is a good idea. I understand the need to make the documentation understandable for newcomers to Scala & SpinalHDL. But doing that at the expense of it as a reference doesn't make sense. People get into SpinalHDL a single time each, but come back for the reference part a whole lot more often (I do so for e.g. looking up details on operators, the type system, simulation loop, etc.) I don't think that splitting the documentation into basically multiple documentations helps. It's fine to have sections that don't immediately appeal to everyone, they might even spark interest into the internals.

And yes you can have thourougly thought out systems what gets put on which branch, but in the end you also need the manpower of people willing to do that work... I'm not sure you want github to just do an automerges to a branch where you expect change to be comitted to, in past projects of mine those only really worked to branches where only the bot merged to (otherwise you end up with merge conflicts where there is no human to fix them)

[Dolu1990]

but in the end you also need the manpower of people willing to do that work

Seems very true to me XD

[numero-744]

People get into SpinalHDL a single time each, but come back for the reference part a whole lot more often

My suggestion is not about initial tutorial vs. detailed documentation explaining operators etc., it is about user documentation (including both tutorial and detailed contents) vs Spinal design / internal stuff explained in "developer area", which is only for SpinalHDL contributors and not for users.

About the master (released) vs dev (not released) split what do you suggest as a solution? We could just keep it as it is currently, I'm okay with it. @Dolu1990 told me the goal of these two branches was to mimic the SpinalHDL repository, but what I don't like with it is that stuff would land on master only when a release is done, so it would not include documentation improvements or documentation added for already published stuff, hence the suggestion.

[Dolu1990]

Maybe, we can just set the default branch to dev, PR would be done there, and the doc would be merged into master on each SpinalHDL release. that kinda not labor intensive.
Down side is that general doc of stuff already existing since long time would not appear on master until next release.

[Readon]

Maybe, we can just set the default branch to dev, PR would be done there, and the doc would be merged into master on each SpinalHDL release. that kinda not labor intensive. Down side is that general doc of stuff already existing since long time would not appear on master until next release.

Is that possible to move RTD documents to SpinalHDL's doc directory, so that it can be simplified?

[numero-744]

Hmm I thought we had already discussed that but I can't find where…

I like this idea. It would simplify #123 and checking the "document your features" rule because documentation would be in the same PR as code.

Maybe we should keep a separate RTD repository to have tutorial contents (the one I'm working on (a lot), following the structure suggested in this issue's description minus some stuff) as a nice entry point for newcomers; and have one for more formal contents (operator definitions, design error descriptions, etc.) inside SpinalHDL/doc/ for more experienced users, following the state of the code?

We could also add another folder for "developers area" to put internal design description for contributors?

[Readon]

Maybe we should keep a separate RTD repository to have tutorial contents (the one I'm working on (a lot), following the structure suggested in this issue's description minus some stuff) as a nice entry point for newcomers; and have one for more formal contents (operator definitions, design error descriptions, etc.) inside SpinalHDL/doc/ for more experienced users, following the state of the code?

Good idea. However, it really is going to be a ton of work.

We could also add another folder for "developers area" to put internal design description for contributors?

In SpinalHDL/doc? It might be all for developers? Could that be "policies to follow"?

[numero-744]

Good idea. However, it really is going to be a ton of work.

You mean sorting and moving stuff, or maintaining on the long term?

For the first one, actually I'm already sorting things on the fly while working on the current issue anyway (from my current experience, writing is way more work than sorting so I think sorting is not even a big deal actually 😅); and moving will be quite simple once things are sorted.

If your comment was about maintaining on the long term, please tell me more

In SpinalHDL/doc? It might be all for developers? Could that be "policies to follow"?

I don't understand but I must admit I wasn't clear too 😅.

What I mean is that we could have in SpinalHDL repository something like this:

• doc/: a Sphinx / RTD documentation for users who are already using SpinalHDL
• doc-internal/: another Sphinx / RTD documentation for users who want to contribute to the internals of SpinalHDL

And keep SpinalDoc-RTD (or move that to another repository, SpinalTutorial for instance) with only a tutorial for new users to discover SpinalHDL and learn how to use it.

If this explanation does not answer your question can you explain me please?

[Readon]

You mean sorting and moving stuff, or maintaining on the long term?

It's just about the sorting & moving. Long term maintains would be easier if reasonable documentation of each PR is required.

• doc/: a Sphinx / RTD documentation for users who are already using SpinalHDL
• doc-internal/: another Sphinx / RTD documentation for users who want to contribute to the internals of SpinalHDL

How about a subdirectory in doc to hold internal things?

And keep SpinalDoc-RTD (or move that to another repository, SpinalTutorial for instance) with only a tutorial for new users to discover SpinalHDL and learn how to use it.

I agree with that. Sync two repositories is a pain.
Is there any weakness that make the documentation split out from the main repository? @Dolu1990

If this explanation does not answer your question can you explain me please?

[numero-744]

How about a subdirectory in doc to hold internal things?

Yes why not, I'm just unsure how to configure that with Sphinx yet 😄

[andreasWallner]

My suggestion is not about initial tutorial vs. detailed documentation explaining operators etc., it is about user documentation (including both tutorial and detailed contents) vs Spinal design / internal stuff explained in "developer area", which is only for SpinalHDL contributors and not for users.

Which assumes that you can find a useful distinction. When I was getting into SpinalHDL I actually found the chapters on Datamodel and Bus Slave implementation quite useful to understand what I'm dealing with.

[andreasWallner]

Is that possible to move RTD documents to SpinalHDL's doc directory, so that it can be simplified?

That would also make versioning the documentation easier, as well as make it easier to run builds for the examples in the documentation (with a matching SpinalHDL version)...

[numero-744]

Fair; I'm looking at it and the thing of "developer area" I often fall on while searching is the "Types" page, which seems to be a messy copy-paste of the pages of the user's "Data types" chapter elsewhere, mixed with examples from Example section. Maybe some sorting/cleaning and using links instead of copy/pasting would be okay?

[andreasWallner]

Fair; I'm looking at it and the thing of "developer area" I often fall on while searching is the "Types" page, which seems to be a messy copy-paste of the pages of the user's "Data types" chapter elsewhere, mixed with examples from Example section. Maybe some sorting/cleaning and using links instead of copy/pasting would be okay?

I think that makes total sense.

Another thing: you want e.g. a contribution guide in the documentation that normal users see - but in the end it's documentation only for those that want to contribute. Same with e.g. the folder structure...