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
• new feature
• 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]

I think that the first option should be "Default" for all the four variables about themes (mkdocs, sphinx and jupyter book)

[xmnlab]

for the profiles/osl.yaml

we should have by default (and visible: False) the documentation engine mkdocs, and the theme material .. osl profile will be very opinionated .. that will be the default structure that we will use for all of our projects.

[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...

[xmnlab]

hi @Anavelyz , thanks for working on that.

in general that looks really good, thanks!

I just add two comments here.

I think that it would be nice if we standardize the value for the options, to be always without space, with dash instead, and all letters in lowercase ...

in this specific case, it would be missing just the step to convert the values to lowercase, for example, PyData -> pydata.

and of course, just in the template variable ... not in the documentation

[xmnlab]

thanks for working on that @Anavelyz .

I saw that a few $ was removed ... I think that probably it would be better to keep that ... but for now I will merge this PR ... so we can discuss and fix that later.

thanks! good job here! appreciate that.

[github-actions]

🎉 This issue has been resolved in version 0.9.0 🎉

The release is available on:

• 0.9.0
• GitHub release

Your semantic-release bot 📦🚀