Turn the user-guide into a sphinx documentation site

SMAT-Lab / Scalpel

Scalpel: The Python Static Analysis Framework

Apache License 2.0

286 stars 43 forks source link

Turn the user-guide into a sphinx documentation site #56

Closed tristanlatr closed 2 years ago

tristanlatr commented 2 years ago

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 commented 2 years ago

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

Jarvx commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

Thanks for the comments

tristanlatr commented 2 years ago

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 commented 2 years ago

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

tristanlatr commented 2 years ago

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