feat(doc-template): adding options for documentation themes

[Anavelyz]

Pull Request description

Adding options for documentation themes:

• MkDocs: Default (mkdocs), Material, Cinder, Readthedocs.
• Sphinx: Default (Alabaster), Readthedocs, PyData
• Jupyter-book: Default (Sphinx Book Theme), PyData-sphinx-theme, Readthedocs-sphinx-theme
• Quarto options: Default, Cosmo, Cerulean, Materia

Fixes #108

Pull Request checklists

This PR is a:

• [ ] bug-fix
• [x] new feature
• [x] maintenance

About this PR:

• [ ] it includes tests.
• [ ] the tests are executed on CI.
• [ ] the tests generate log file(s) (path).
• [ ] pre-commit hooks were executed locally.
• [ ] this PR requires a project documentation update.

Author's checklist:

• [ ] I have reviewed the changes and it contains no misspelling.
• [ ] The code is well commented, especially in the parts that contain more complexity.
• [ ] New and old tests passed locally.

Additional information

• [ ] I managed to reproduce the problem locally from the main branch
• [ ] I managed to test the new changes locally
• [ ] I confirm that the issues mentioned were fixed/resolved

[xmnlab]

@Anavelyz ... thanks for working on that. in general it looks good.

testing it with sphinx, the command makim.preview failed:

building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 7 source files that are out of date
updating environment: [new config] 7 added, 0 changed, 0 removed
/tmp/osl/osl-python-package/docs/changelog.md:2: ERROR: Document or section may not begin with a transition.
/tmp/osl/osl-python-package/docs/changelog.md:2: ERROR: Document may not end with a transition.

Notebook error:
PandocMissing in example.ipynb:
Pandoc wasn't found.
Please check that pandoc is installed:
https://pandoc.org/installing.html
Traceback (most recent call last):
  File "/tmp/tmp5u7gusuw.makim", line 1, in <module>
    sphinx-build -M html docs/ docs/_build/
Makim Error #1: 
/home/xmn/miniforge3/envs/osl-python-package/bin/xonsh 
/tmp/tmp5u7gusuw.makim

could you check that please? I didn't test the command makim docs.preview command with jupyter-book .. for quarto ... not sure if it is something expected or not .. but for most of the themes it pops up a window with a label for render every time I click on a menu .. could you check that as well please?

thanks!

[xmnlab]

also I found some issues in the documentation, with mkdocs, as you can see in this image:

it is not specific for this PR, but it would be nice to fish that for this set of issues for the PSF grant.

[Anavelyz]

@Anavelyz ... thanks for working on that. in general it looks good.

testing it with sphinx, the command makim.preview failed:

building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 7 source files that are out of date
updating environment: [new config] 7 added, 0 changed, 0 removed
/tmp/osl/osl-python-package/docs/changelog.md:2: ERROR: Document or section may not begin with a transition.
/tmp/osl/osl-python-package/docs/changelog.md:2: ERROR: Document may not end with a transition.

Notebook error:
PandocMissing in example.ipynb:
Pandoc wasn't found.
Please check that pandoc is installed:
https://pandoc.org/installing.html
Traceback (most recent call last):
  File "/tmp/tmp5u7gusuw.makim", line 1, in <module>
    sphinx-build -M html docs/ docs/_build/
Makim Error #1: 
/home/xmn/miniforge3/envs/osl-python-package/bin/xonsh 
/tmp/tmp5u7gusuw.makim

could you check that please? I didn't test the command makim docs.preview command with jupyter-book .. for quarto ... not sure if it is something expected or not .. but for most of the themes it pops up a window with a label for render every time I click on a menu .. could you check that as well please?

thanks!

I was checking and the error is because pandoc is not installed correctly, in pip there is an outdated version.

In the documentation they recommend to use conda, I tried it locally and the error disappears...