Turn the user-guide into a sphinx documentation site

[tristanlatr]

I believe it could make it more useful for end users to have both the API documentation ans the user guides at the same place and be able to link from narrative docs to the API documents.

If this is something that you'd like, I can work on turning the user guides into a sphinx project, using markdown. Then we'll be able to upload it to readthedocs very easily ;-)

Tell me what you think,

[Jarvx]

@tristanlatr I really appreciate your help. This is a really wonderful idea. I will let you know after discussing it with other developers.

[Jarvx]

I believe it could make it more useful for end users to have both the API documentation ans the user guides at the same place and be able to link from narrative docs to the API documents.

If this is something that you'd like, I can work on turning the user guides into a sphinx project, using markdown. Then we'll be able to upload it to readthedocs very easily ;-)

Tell me what you think,

@tristanlatr Thank you. Please do so and then we will work with you.

[tristanlatr]

Could you please leave this issue open until a PR that fixes this issue is merged?

Also, I noticed there is already a project named « scalpel » on readthedocs: https://scalpel.readthedocs.io/en/latest/ so we’ll have to find another project url if we want to host the docs on readthedocs.

[Jarvx]

Thanks for the comments

[tristanlatr]

Hi, I'm working on this and I have a couple of questions:

• Can the scalpel-book be deleted ? It seems that it does not contain any relevant informations.
• You'r API docs seems to reside in the docs/ folder, I'm unsure if the current setup re-gerenrate the API docs every time. But I'de suggest to use something integrated with sphinx (that works by static analysis), like sphinx-autoapi or pydoctor.
• I'de suggest to relocate everything (user-guide and resources) under the docs folder and adopt a standard sphinx setup in this folder. This would mean that the HTLM pages of the API documentation would not reside in the main bran of the repository, but only in the gh-pages branch and generated at every push to the main branch.
• Also I'm a bit lost about main branch vs scalpel-dev branch, seems that you accept pull requests on both, so I'm not sure from which I should start working.

Tell me what you think.

[Jarvx]

@tristanlatr Thanks for your suggestions and I will clean the project very soon.

[tristanlatr]

@Jarvx see my work in progress here: https://github.com/SMAT-Lab/Scalpel/pull/70