sphinx project setup

[tristanlatr]

This PR is a work in progress. API docs are still missing and stuff is broken at some places.

[tristanlatr]

This PR does not include the tooling to generated the documentation at every push. It can be done later.
To generate the documentation locally, install tox and run tox -e docs, then run

python3 -m http.server -d ./build/docs/en

to serve your docs at http://localhost:8000/.

The documentation include the API docs as well and links from guides to the API docs are made at the end of each file.

[tristanlatr]

Can you explain to me what’s the next step with these changes ?

[Jarvx]

@tristanlatr I really like the idea that separating the docs and code repos as you mentioned . I have created a new repo for readthedocs at. https://github.com/SMAT-Lab/python-scalpel and I will push the htmls to the new repo very soon.

Thank you very much for your contribution. Meanwhile, if you have other suggestions, please feel free to share.

I am planning for new functionalities and API for the next stage of development at the moment, so really glad to hear from you.

[Jarvx]

This is just to mark the progress.

[tristanlatr]

The documentation should live in the same repository, it’s like a common practice. Also it makes things more easier if you want to have both the api docs and the user guides at the same place. I’m not sure to understand what’s going on with this PR?

[tristanlatr]

We can setup the repository on readthedocs even if the « scalpel » has already been taken, then it’s not necessary to have another repository for the documentation

[Jarvx]

Thanks for clarifying. I just want to make things easier. Honestly, I am not good at dealing with documentation applications. I simply followed readthedocs template. I will see what to do next to setup up a doc site.

But for sure, I will generate the docs and push to /doc first (might tmr!).

Sorry, I am really busy this week, but let's keep all discussions here until everything is set up.

[tristanlatr]

Thanks for clarifying. I just want to make things easier. Honestly, I am not good at dealing with documentation applications

I am good at setting up project documentation. So you can trust me when I said that the docs folder is not the place to store the html files, it’s the place to store the source of the Sphinx site. The html files should be hosted on a separate branch or completely somewhere else.

[Jarvx]

Okay, will do it next and will let you know when finished! Thanks.

[tristanlatr]

Okay, will do it next and will let you know when finished! Thanks.

to be clear, the next step should be to create a account at readthedocs.org, create a new project named whatever you like (not scalpel because it’s already taken), import that repository to this project, setup the webhook on the repository settings, and that’s it, finished.

[tristanlatr]

Oh and there is something with adding the readthedocs.yml file at the root of the repository as well.