Link to the scaladoc page

[wifasoi]

We should use more linking to the scaladoc page (http://spinalhdl.github.io/SpinalHDL). There should be a TOC entry somewhere to link it, and a hyperlink for each function/class in the documentation.

this from a discussion in #25

[numero-744]

There are different approaches:

• Use ScalaDoc for documentation, in RTD put only tutorial stuff with links to documentation
• Try to maintain the same documentation both in RTD and ScalaDocs
• Use RTD for both tutorial and documentation stuff (current situation) and in ScalaDoc only put a short description and add links to RTD, so that IDEs can show them
• Other approaches?

IMO:

• the first one is better but I think it is more the way software people think and may not be good for hardware people
• the second one is not maintainable
• the third one is a suitable alternative, and maybe the best if targeting hardware people

[wifasoi]

IMO opinion it should be fot design concept, getting started and a quick reference for basic stuff. Full reference should be delegetaed to a Future™️ scaladoc versioned page. Now that we have the power of Github action, we can accomplish this. Unfortunally for us, there is no a ready to use scaladoc action D: , but we can use the scala-sbt one and compile the docs in that way. Do you want work on this? Otherwise I can massage this task in my project queue :D

[numero-744]

I find this topic interesting enough to work on it, but I think I will not have time for it (moving documentation from RTD to SpinalDoc + maybe review some stuff, get sure everything is correctly documented) before December :sweat_smile:.

[Dolu1990]

in RTD put only tutorial stuff with links to documentation

Isn't the ScalaDoc just too flat structuraly to provide comprensive user navigation / discovery ?

Also, the Scala internal DSL tricks will quite often obsucate what the user can do.

[numero-744]

@Dolu1990 IMO discovery can be done through tutorials, and navigation is, well, API + "see also" links. Do you have an example use-case where it could be an issue?

For the DSL tricks, do you have an example of place where it could be obfuscating what the user can do?

[Dolu1990]

For instance, all the implicit convertions which can also provide functions : https://github.com/SpinalHDL/SpinalHDL/blob/dev/lib/src/main/scala/spinal/lib.scala#L57

[numero-744]

What about:

• for general stuff for designers: Use RTD for both tutorial and documentation stuff (current situation) and in ScalaDoc only put a short description and add links to RTD, so that IDEs can show them.
• for internals & advanced usage requiring software skills: Use ScalaDoc for documentation, in RTD put only tutorial stuff with links to ScalaDoc

[Dolu1990]

for general stuff for designers: Use RTD for both tutorial and documentation stuff (current situation) and in ScalaDoc only put a short description and add links to RTD, so that IDEs can show them

+1

for internals & advanced usage requiring software skills: Use ScalaDoc for documentation, in RTD put only tutorial stuff with links to ScalaDoc

+1

all ok

[numero-744]

Note about ScalaDoc:

The rendering for SpinalHDL is quite poor ("so 2000" style), compared for instance with https://www.scalatest.org/scaladoc/3.2.14/org/scalatest/flatspec/AnyFlatSpec.html

Any idea why?

[Dolu1990]

No idea ^^

[numero-744]

A label "docs needed" has been created in SpinalHDL repo. It is added when there is no RTD (or issue in SpinalDoc-RTD) for it, and when there is not enough Scaladoc (documentation or link to RTD).

Please do not merge PRs with this label.

I think this issue can be closed.