Open numero-744 opened 2 years ago
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.
Do you think it's better to describe things as sections below:
...
Although, this would make a deep tree, or we can use this definition constantly.
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: https://github.com/SpinalHDL/SpinalDoc-RTD/issues/151#issuecomment-1321369491 You are receiving this because you were assigned.
Message ID: @.***>
Fondamentaly, we can have both, both aproache fit different situations.
Having two parallel tables of contents?
As long there is not a table of table of contents
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.
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.
So I suggest to first go for this structure, and with the result see if something else should be added for other cases
fine to me ^^
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.
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 :sweat_smile:). I won't PR for this issue until 1.8 is released (there are few PRs to merge before that :crossed_fingers:), 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.
dev
(so that PRs go on this by default)master
(for most users)master
if it is about a documented feature.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?
@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)
but in the end you also need the manpower of people willing to do that work
Seems very true to me XD
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.
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.
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?
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?
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"?
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 :sweat_smile:); 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 :sweat_smile:.
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 SpinalHDLdoc-internal/
: another Sphinx / RTD documentation for users who want to contribute to the internals of SpinalHDLAnd 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?
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 SpinalHDLdoc-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 discoverSpinalHDL
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?
How about a subdirectory in doc to hold internal things?
Yes why not, I'm just unsure how to configure that with Sphinx yet :smile:
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.
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)...
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?
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...
The goal is to both:
Root:
if
,for
, also mentionnull
and mutability)inout
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
anddev
in parallel:dev
has this andmaster
doesn't.Pushing/merging into master automatically opens a PR from
master
todev
, and contributions to this section are PR'd todev
.Or maybe even two separate branches with completely different contents.
For reference, structure is inspired from: https://doc.rust-lang.org/stable/book/