Replace sphinx with mkdocs and move setup.cfg to pyproject.toml

[FlorianWilhelm]

Trying to fix those Sphinx warnings from #90 one way or another.

[coveralls]

Pull Request Test Coverage Report for Build 6441160223227904

• 1 of 1 (100.0%) changed or added relevant line in 1 file are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 97.608%

---

Totals
Change from base Build 4537812213563392:	0.0%
Covered Lines:	857
Relevant Lines:	873

---

💛 - Coveralls

[abravalheri]

Hi @FlorianWilhelm, thank you very much for the huge amount of work you are pouring into this...

Do we need to pull in hatch for this job?

Would ignore the warnings be a valid option for handling this problem? If this problem was reported in sphinx maybe it will eventually be fixed?

[FlorianWilhelm]

@abravalheri, hatch is not needed and I think we should keep it to setuptools only as PyScaffold does it the same way. I thought I give the new setuptools features a test run and also mkdocs for this. mkdocs really is so much easier to handle compared to Sphinx... but I can of course understand if it would give a wrong message if configupdater was using mkdocs and PyScaffold not. So I am completely open and would follow your suggestion.

There are mainly 2 questions:

1. Should we adapt pyproject.toml-only using setuptools to have a test run for the next PyScaffold version?

2. Should we replace Sphinx with mkdocs? Maybe to also evaluate as it might be a way more lightweight alternative to Sphinx for an upcoming PyScaffold release. It's the first time I am trying mkdocs with RTD and it seems to work just fine.

3. and 2) are rather independent of each other. We could also just keep it as it is. Your call :-)

P.S.: If we want to go for 1) we could use your ini2toml tool in a separate PR first and see if it works. It was rather a mistake by myself to mix to things in one PR.

[FlorianWilhelm]

@abravalheri: Regarding ignoring the warnings, I am not sure it really is considered a bug in Sphinx napoleon, from all I understand I would rather say it's a kind of design decision for them but I might also be wrong.

[abravalheri]

Hi @FlorianWilhelm,

Should we adapt pyproject.toml-only using setuptools to have a test run for the next PyScaffold version?

Definitely! There is some initial work contributed to the dev branch, but I have been very slow lately :P

Should we replace Sphinx with mkdocs? Maybe to also evaluate as it might be a way more lightweight alternative to Sphinx for an upcoming PyScaffold release. It's the first time I am trying mkdocs with RTD and it seems to work just fine.

I have no objection on that front, in fact we can use this opportunity and extract templates either for PyScaffold itself or pyscaffoldext-mkdocs.

Do you know what are the main advantages of mkdocs over sphinx+MyST?
I was really impressed by the work that the Executable Books team has been doing with Sphinx+MyST lately, and the fact that integrates smoothly with jupyter.

[FlorianWilhelm]

Okay, then I would suggest I wait a little longer until there is a state of PyScaffold that we can try to automatically update ConfigUpdater, which I can then try out to move it to pyproject.toml only.

Regarding Sphinx vs. mkdocs, let's then stay with Sphinx+MyST :-) Surely Sphinx with all its extensions is still way more powerful than mkdocs. For some tiny side projects I just tend to use mkdocs since it's so much simpler and I can do everything in a toml file and per default it's markdown.

Let's close this PR for now then :-)

[abravalheri]

Regarding ignoring the warnings, I am not sure it really is considered a bug in Sphinx napoleon

It seems that there are a few issues open in sphinx that might be related to this. One of them seem to have some traction and the overall idea seems to be supported by the leading dev (although no implementation is available yet).

from all I understand I would rather say it's a kind of design decision for them but I might also be wrong.

Yes that is probably sphinx nudging that apidoc is a great start, but that probably when a project gets bigger, exposing just a subset of public APIs via autodoc results in a "more controlled" outcome...