search

jgori-ouistiti / CoopIHC

Two-agent component-based interaction environments for computational HCI with Python
https://jgori-ouistiti.github.io/CoopIHC/
MIT License
1 stars 1 forks source link

standard and dev documentation #30

Closed jgori-ouistiti closed 2 years ago

jgori-ouistiti commented 2 years ago

Is your feature request related to a problem? Please describe. It would be nice to have two versions of the documentation, one dev and one non-dev

Describe the solution you'd like two entirely different sphinx documentations, generated from the same document, towards to different branches. Something like make html-dev and make html run on the same doc would turn out into two different end results that can co exist.

Describe alternatives you've considered No dev documentation using sphinx (maybe a couple of md files can do), or dev documentation added (possibly hidden) in the standard doc

Additional context For the dev documentation, to add hidden members this could be useful: https://stackoverflow.com/questions/62142793/autosummary-generated-documentation-missing-all-dunder-methods-except-for-ini

jgori-ouistiti commented 2 years ago

the current sphinx action supports a per branch documentation, so we could have a dev-doc branch. But that solves only part of the problem in that it would be nice to have to maintain a single document

christophajohns commented 2 years ago

What do you see as part of the dev documentation but not the user documentation? Many projects I've seen have the developer or contributing section as part of their official documentation (after all, you want regular users to become contributors anyways; see for example https://numpy.org/doc/stable/dev/index.html or https://reactjs.org/docs/how-to-contribute.html).

jgori-ouistiti commented 2 years ago

it would be nice to have information regarding building the package + sphinx but I don't think it should be visible to the typical end-user. But I get your point that if you want a user to transition to a contributor, access to these docs should be easy. Maybe add a non-referenced page and give the link in the contributing.md would do?

christophajohns commented 2 years ago

If you want to hide build instructions from published documentation, you can also put that into the repo's wiki here on GitHub. Haven't used that or seen that in use so far though.

jgori-ouistiti commented 2 years ago

I'm convinced info in contributing.md is enough, so I'm closing this issue