Refactor step 1

[numero-744]

This is the first part of my refactoring work.

You can see it live on https://numero-744.github.io/SpinalDoc-RTD/master/

For review I suggest to visit the site and the first pages of the PDF. I stopped just before 2.6 Scala Guide.

Things to discuss:

• Section 1.2.2, page 4: references to prove companies are using SpinalHDL (like Wikipedia's reference needed tag)
• Section 1.3, page 5: is StackOverflow maintained? Do we have a better link than just stackoverflow.com?
• Section 1.3, page 5: Is Google group still maintained?
• Section 2.1.4, page 11: Explain the directory structure (we can define one in Document scala file path #147 else I can explain the one from SBT)
• Section 1.7, page 7: Is Jupyter bootcamp still mantained?
• Section 1.7, page 7: Is Workshop still maintained?
• Page 1: idea to add a foreword about why SpinalHDL, from page 5 of taste.pdf (or motivation.pdf, I think it is the same file)

Close #149 and #147

[Readon]

If the refactor is necessary, I suggest that add a "Design philosophy" behind the "A simple example" section.
The section helps newcomer to understand what does Scala do, SpinalHDL do and Verilog/VHDL/SystemVerilog do in the whole flow.
A diagram of the flow can be useful for explaining what's their role.

[numero-744]

Yes we should add that, but I think it would go in the introduction? Between What is SpinalHDL and Advantages …?

[numero-744]

In presentation.pdf, there is the page 4 which can be good to explain that (with a diagram)

[numero-744]

Tbh I think this PR is big enough for a review, I can open an issue to do that in a subsequent PR @Readon ?

[Readon]

Sometimes, I have imaging that I am a starter of SpinalHDL, and check over the documentation,
I would be confused by the structure of the docs.

The questions strike me up.

1. Why "Structuring", "Semantic", "Sequential logic" are separated, what's the purpose for them?
2. Why there is no "Combination logic" if "Sequential logic" is there?
3. What are "other language features" to do?
4. What is the role of the Libraries? Does it different from other section?
5. What should I learn if I never played any HDL before? (That can be assumed never happen in this stage.)
   ....

The problems are that the docs are read by many people with different background.
Is it necessary to make the doc's hierarchy reasonable by compromise on more navigating depth?

[Readon]

Yes we should add that, but I think it would go in the introduction? Between What is SpinalHDL and Advantages …?

As a reader, an example is much more useful at first. Later than that, a deeper explanation can help to understand.

[numero-744]

Yea this is the goad of this refactoring, here is just the very beginning.

---

So there would be an example in the introduction, and then a kind of little at the end of Getting Started?

[numero-744]

Do we have the sources of the 2 pdf files? So that I could maybe simply extract visual contents as svg's?

[Dolu1990]

A simple example <3

[numero-744]

About the final structure to give, I have sent a suggestion in #151

I think all discussions about parts of the structure which are not modified yet, and sections to add should be in #151.
Here let's discuss modifications to perform on this PR (and the things I mentioned in the issue description, please).

[numero-744]

I have updated after your suggestions, I still need answers for the remaining questions in the description

[Readon]

• Section 1.2.2, page 4: references to prove companies are using SpinalHDL (like Wikipedia's reference needed tag)
• Section 1.3, page 5: is StackOverflow maintained? Do we have a better link than just stackoverflow.com?
• Section 1.3, page 5: Is Google group still maintained?
• Section 1.7, page 7: Is Jupyter bootcamp still mantained?
• Section 1.7, page 7: Is Workshop still maintained?

About the activities, I think bootcamp and workshop is still working.

[numero-744]

Bootcamp: It is a fork of a @jijingg repository, and the fork is a few commits late…

Maybe we could move the original repository to maintain it all together as a part of Spinal repositories? Also I found that it (the fork) uses version 1.6.0 https://github.com/SpinalHDL/Spinal-bootcamp/blob/dev/exercises/build.sc#L5

Workshop is less late, 1.7.0a https://github.com/SpinalHDL/SpinalWorkshop/blob/workshop/build.sbt#L6

So tell me if I am wrong, I can define the workshop as a set of exercises (maybe I can point to exercises all along the tutorial part?), and bootcamp as an interactive tutorial?

[Readon]

Bootcamp: It is a fork of a @jijingg repository, and the fork is a few commits late…

Maybe we could move the original repository to maintain it all together as a part of Spinal repositories? Also I found that it (the fork) uses version 1.6.0 https://github.com/SpinalHDL/Spinal-bootcamp/blob/dev/exercises/build.sc#L5

Workshop is less late, 1.7.0a https://github.com/SpinalHDL/SpinalWorkshop/blob/workshop/build.sbt#L6

So tell me if I am wrong, I can define the workshop as a set of exercises (maybe I can point to exercises all along the tutorial part?), and bootcamp as an interactive tutorial?

They are all tutorials, and they don't necessarily need to be updated to the latest often, as long as the API remains the same. ^^

[numero-744]

Thanks, updated.

For StackOverflow and Google groups, are there people still using them?

For the last point, an agreement about #147 (sbt, SaxonSoc, SpinalHDL/SpinalTemplateSbt#23 or another structure) coming first would be appreciated; else I have to document a complex structure that I think is not good for hardware description, without knowing if it will be kept in the next weeks 😅

Also don't forget, it would be nice to have references about companies using SpinalHDL (for instance an article explaining what they do, why they use SpinalHDL and such things).

[Dolu1990]

Bootcamp: It is a fork of a @jijingg repository, and the fork is a few commits late…

Maybe we could move the original repository to maintain it all together as a part of Spinal repositories? Also I found that it (the fork) uses version 1.6.0 https://github.com/SpinalHDL/Spinal-bootcamp/blob/dev/exercises/build.sc#L5

Workshop is less late, 1.7.0a https://github.com/SpinalHDL/SpinalWorkshop/blob/workshop/build.sbt#L6

So tell me if I am wrong, I can define the workshop as a set of exercises (maybe I can point to exercises all along the tutorial part?), and bootcamp as an interactive tutorial?

The thing about maintenance and maintained code, is that man power is realy low in general, can't keep everything all the time up to the last revision, as it take time to update / test / verify. So in some way, it is sometime better to keep things in a state they were known to work, than updating and silently breaking stuff.

[Dolu1990]

Google groups

It is mostly use as a way to push notification so far XD
Not much used, but still can be usefull

[numero-744]

Yea, this is why I documented these other tutorials as not having the latest features in my last commits.

For Google groups, as long as a new user sending a question there gets an answer it is okay for me ^^

And for Stackoverflow? Do I remove it?

[numero-744]

Ah, one more thing: https://github.com/SpinalHDL/Spinal-bootcamp being a fork has a maintenance cost that it needs to be sync'd by-hand. And if we don't sync we waste maintenance of the person who added commits to it.

So maybe we could ask to move the original repository instead of having a fork, or directly point to the original repository?

[Dolu1990]

So maybe we could ask to move the original repository instead of having a fork, or directly point to the original repository?

yes.
@jijingg As you want :)

[numero-744]

All the TODOs are checked, but please don't merge before SpinalHDL/SpinalTemplateSbt#23 is merged.

I have removed the "reference needed" for this PR but it would still be better if we had some

[numero-744]

The template has been updated so I think this PR can be merged now.

[Dolu1990]

https://numero-744.github.io/SpinalDoc-RTD/master/SpinalHDL/Introduction/Getting%20in%20touch.html need a bit of work i think.

I would say : Google group is used as a mailing list to get notification when there is a event or something.

Stackoverflow, i realy have no idea, i'm not sure it is worth mentioning it, as there is nothing special there ?

[Dolu1990]

(else i think this look good ^^)

[Dolu1990]

Good to me.

[numero-744]

@Dolu1990 Sorry I forgot to update https://numero-744.github.io/SpinalDoc-RTD/master/ it should be okay now (reloading the page may be needed) https://numero-744.github.io/SpinalDoc-RTD/master/SpinalHDL/Introduction/Getting%20in%20touch.html

[Dolu1990]

Ahhh right ^^