hopsan icon indicating copy to clipboard operation
hopsan copied to clipboard
verified publisher icon Hopsan

Markdown documentation for all components in default library

Open robbr48 opened this issue 5 years ago • 3 comments

Is your improvement request related to a problem? Please describe. Documentation is poor for many components in default library.

Describe the solution you'd like Specify markdown documentation (or PDF) for each component in default library.

I will not specify a milestone for this issue, since it will likely take a while before it is complete.

  • [ ] Connectivity
  • [ ] Electric
  • [ ] Experimental
  • [ ] Hydraulic
    • [ ] HydroDynamicComponents
    • [ ] LinearActuators
    • [ ] MachineParts
    • [ ] Pumps&Motors
    • [ ] Restrictors
    • [ ] Sensors
    • [ ] Sources&Sinks
    • [ ] Special
    • [ ] Valves
      • [ ] DirectionalValves
      • [ ] FlowControlValves
      • [ ] PressurControlled
      • [ ] PressurControlValves
    • [ ] Volumes&Lines
  • [ ] Mechanic
    • [ ] Linear
    • [ ] Rotational
  • [ ] Obsolete
  • [ ] Pneumatic
  • [ ] Signal
    • [ ] Animation
    • [ ] Arithmetics
    • [ ] Control
    • [ ] Filters
    • [ ] Logic
    • [ ] MathFunctions
    • [ ] Navigation
    • [ ] Non-Linearities
    • [ ] SignalFFB
    • [ ] SignalRouting
    • [ ] Sources&Sink
  • [ ] Special
    • [ ] AeroComponents
    • [ ] Benchmarking
    • [ ] MechanicB
    • [ ] OptimizationTestFunctions
    • [ ] TMMS04

robbr48 avatar Aug 20 '20 11:08 robbr48

@larsviktorlarsson

Expected behavior All components should have descriptions, perhaps it should always be in .md format? Since this fix will take a long time, maybe one should open a pull request which anyone interested could commit to?

I think we should allow other formats than .md, but encourage the use of it.

Having a single pull request for the issue is possible, but requires some git more knowledge since it involves creating pull requests to personal repositories. Using individual PRs is a simpler solution. We should write a message here before we start working though, so that multple people don't work on the same components.

robbr48 avatar Aug 21 '20 07:08 robbr48

Yes that sounds good!

larsviktorlarsson avatar Aug 21 '20 07:08 larsviktorlarsson

Could create a separate "feature branch" but maybe PRs are better to enable review. Plain HTML can also be used, and I think that the auto generated components use that.

Also an unresolved issue with markdown is that we need to start with heading level 3 to make it look resonable. But it should be possible to write CSS or something to control the appearance of the generated HTML.

We should also have a template for how the documentation should be structured.

peterNordin avatar Aug 21 '20 13:08 peterNordin