feat(template): Add API documentation to the template 2/4 (Sphinx) #124

YurelyCamacho · 2023-06-12T23:03:43Z

Pull Request description

Add the necessary dependencies in pyproject.toml and conf.py, to generate the API documentation with sphinx.
Remove unusable file in sphinx (post_gen_project.py)
Create and edit the file for automatic API documentation.
Edit the index.rst with all the files

src/scicookie/{{cookiecutter.project_slug}}/docs-sphinx/index.rst

xmnlab · 2023-06-12T23:31:27Z

src/scicookie/{{cookiecutter.project_slug}}/docs-sphinx/readme.rst

@@ -1 +1,4 @@
+Introduction


I think that now I got the point you mentioned on discord.
that makes more sense to call this file to intro.rst
also please rename it https://github.com/osl-incubator/scicookie/pull/124/files#diff-e5704837157913d9457988b9450bc2f363e27663bd5e2ecd098e580a44e9adb9R11

xmnlab

thanks for working on that @YurelyCamacho
in general it looks good to me.
just added few comments here.
thanks!

Co-authored-by: Ivan Ogasawara <[email protected]>

YurelyCamacho · 2023-06-12T23:18:31Z

src/scicookie/{{cookiecutter.project_slug}}/docs-sphinx/index.rst

@xmnlab We have several comments here:

In line 4, we add the README directly, so that it appears as an introduction. When generating the documentation, sphinx does not recognise titles starting with #. The same happens when we create a link to an introduction page (where we use the readme.rst file already created). If you add ../README.md to the index, this link will not be generated. The same situation occurs if readme.rst has no title.

There is a problem generating the contents of the example.ipynb notebook. It says that the title is not recognised and therefore it does not generate it.

@xmnlab The issue here is whether to leave the readme as in line 4 or 11? And any suggestions on how to solve the problem of not recognising the headers (which are in md with #)?

ok give me until tomorrow to digest all of this and I will be back here tomorrow
thanks for your work here!

@YurelyCamacho, I am back here. I got the problem now. sorry for being late ...
I am investigating it now and I will be back here in a bit.

reading a bit this SO: https://stackoverflow.com/questions/46278683/include-my-markdown-readme-into-sphinx

it seems it has 3 options:

using symlink https://stackoverflow.com/a/48931594

creating a new file inside the docs folder that includes the README https://stackoverflow.com/a/68005314

not sure if it would be necessary to add a recommonmark as a (dev) dependency

@xmnlab We will try to see if it works for us and let you know, thanks

@xmnlab Do you prefer the readme to appear on the first page (as an introduction) with the table of contents or in a link called introduction?
We have already resolved the issue of titles. What it still doesn't show us is the notebook information example.ipynb.

I don't have a strong opinion about that right now
so feel free to pick one that you think that would be better.
maybe soon we can get some feedback from some users and change it if it is necessary.

could you ping me tomorrow so we can see this issue with example.ipynb together?

could you ping me tomorrow so we can see this issue with example.ipynb together?

All right, see you tomorrow

xmnlab · 2023-06-15T01:11:34Z

@YurelyCamacho it seems that src/scicookie/{{cookiecutter.project_slug}}/pyproject.toml has a git conflict

YurelyCamacho · 2023-06-16T19:29:44Z

@xmnlab We made a few changes and locally all the documentation now shows up fine, with the readme as a link called Introduction and the notebook called Example.
On my machine, I had to install pandoc using the package manager. I put pandoc as a dependency in the pyproject.toml, but it gives an error with pandoc. What do you suggest?

xmnlab · 2023-06-16T19:47:06Z

@YurelyCamacho it seems that the problem is about the pandoc package from pypi: https://stackoverflow.com/questions/62398231/building-docs-fails-due-to-missing-pandoc

probably the way to go is to add pandoc just in the conda env.
as it is a dev dependency, that would be ok.

just not sure if the user decided to not use conda XD
but it would be a problem for the future!

let me know if that solutions works for you

xmnlab · 2023-06-16T20:01:29Z

@YurelyCamacho it seems we will need both packages, one installed by conda and the other one by poetry.
a friend pointed my this (from the documentation on pypi):

Pandoc – the general markup converter (and Haskell library) written by John MacFarlane – needs to be available. You may follow the official installation instructions or use conda:

$ conda install -c conda-forge pandoc
Then, install the latest stable version of the pandoc Python library with pip:

$ pip install --upgrade pandoc

Anavelyz · 2023-06-16T20:48:31Z

src/scicookie/{{cookiecutter.project_slug}}/conda/dev.yaml

@@ -7,3 +7,4 @@ dependencies:
  - poetry
  - nodejs  # used by semantic-release
  - shellcheck
+  - pandoc


@xmnlab @YurelyCamacho I think it should be:

Suggested change

- pandoc

{% if cookiecutter.documentation_engine == 'sphinx' -%}

- pandoc

{% endif %}

Am I right?

@YurelyCamacho could implement this idea @Anavelyz suggested?
please just to ensure to use the jinja tags correctly .. maybe:

{% if cookiecutter.documentation_engine == 'sphinx' -%} - pandoc {%- endif %}

@YurelyCamacho maybe you can try this:

{%- if cookiecutter.documentation_engine == 'sphinx' %} - pandoc {%- endif %}

btw, I recommend you to play with: http://jinja.quantprogramming.com/

for this case, you can use as value (yaml), this input:

cookiecutter: project_slug: test documentation_engine: sphinx

xmnlab · 2023-06-16T23:24:05Z

https://github.com/osl-incubator/scicookie/actions/runs/5294889705/jobs/9584695651?pr=124#step:5:355

@YurelyCamacho it seems that the tag jinja2 in the conda env file is not working properly yet with the fix-end-of-file pre-commit XD
ping me again when this PR is ready again for review :)

YurelyCamacho · 2023-06-17T00:39:42Z

@xmnlab Done

xmnlab · 2023-06-17T01:09:38Z

thanks @YurelyCamacho !

github-actions · 2023-06-17T01:16:57Z

🎉 This PR is included in version 0.2.0 🎉

The release is available on:

0.2.0
GitHub release

Your semantic-release bot 📦🚀

add API documentation for sphinx

b3989c9

YurelyCamacho requested a review from xmnlab June 12, 2023 23:20

xmnlab reviewed Jun 12, 2023

View reviewed changes

src/scicookie/{{cookiecutter.project_slug}}/docs-sphinx/index.rst Outdated Show resolved Hide resolved

xmnlab reviewed Jun 12, 2023

View reviewed changes

xmnlab requested changes Jun 12, 2023

View reviewed changes

Update index.rst

d096e0f

Co-authored-by: Ivan Ogasawara <[email protected]>

YurelyCamacho commented Jun 13, 2023

View reviewed changes

YurelyCamacho requested a review from xmnlab June 13, 2023 00:36

YurelyCamacho added 6 commits June 16, 2023 11:48

Merge remote-tracking branch 'upstream/main' into sphinx

145d206

update documentation for sphinx

1e186bc

fix error in notebook

607c0cc

add empty cell at the end of the file

fc491ac

add title for notebook

efef37d

add pandoc dependencie

1bfd7b0

YurelyCamacho marked this pull request as ready for review June 16, 2023 19:27

YurelyCamacho added 2 commits June 16, 2023 16:02

Merge remote-tracking branch 'upstream/main' into sphinx

7a4f820

add pandoc

638b05d

Anavelyz reviewed Jun 16, 2023

View reviewed changes

add conditional sentence

6c7f19c

fix conditional sentence

6b47f74

xmnlab merged commit e3b2baf into osl-incubator:main Jun 17, 2023

xmnlab changed the title ~~feature(template): Add API documentation to the template 2/4 (Sphinx)~~ feat(template): Add API documentation to the template 2/4 (Sphinx) Jun 17, 2023

github-actions bot added the released label Jun 17, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(template): Add API documentation to the template 2/4 (Sphinx) #124

feat(template): Add API documentation to the template 2/4 (Sphinx) #124

YurelyCamacho commented Jun 12, 2023 •

edited

Loading

xmnlab Jun 12, 2023

xmnlab left a comment

YurelyCamacho Jun 12, 2023

YurelyCamacho Jun 13, 2023

xmnlab Jun 13, 2023

xmnlab Jun 14, 2023

xmnlab Jun 14, 2023

YurelyCamacho Jun 14, 2023 •

edited

Loading

YurelyCamacho Jun 15, 2023

xmnlab Jun 15, 2023

xmnlab Jun 15, 2023

YurelyCamacho Jun 15, 2023

xmnlab commented Jun 15, 2023

YurelyCamacho commented Jun 16, 2023

xmnlab commented Jun 16, 2023

xmnlab commented Jun 16, 2023

Anavelyz Jun 16, 2023

xmnlab Jun 16, 2023 •

edited

Loading

xmnlab Jun 16, 2023

xmnlab commented Jun 16, 2023

YurelyCamacho commented Jun 17, 2023

xmnlab commented Jun 17, 2023

github-actions bot commented Jun 17, 2023

-  - pandoc
+{% if cookiecutter.documentation_engine == 'sphinx' -%}
+  - pandoc
+ {% endif %}

feat(template): Add API documentation to the template 2/4 (Sphinx) #124

feat(template): Add API documentation to the template 2/4 (Sphinx) #124

Conversation

YurelyCamacho commented Jun 12, 2023 • edited Loading

Pull Request description

Choose a reason for hiding this comment

xmnlab left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

YurelyCamacho Jun 14, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xmnlab commented Jun 15, 2023

YurelyCamacho commented Jun 16, 2023

xmnlab commented Jun 16, 2023

xmnlab commented Jun 16, 2023

Choose a reason for hiding this comment

xmnlab Jun 16, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xmnlab commented Jun 16, 2023

YurelyCamacho commented Jun 17, 2023

xmnlab commented Jun 17, 2023

github-actions bot commented Jun 17, 2023

YurelyCamacho commented Jun 12, 2023 •

edited

Loading

YurelyCamacho Jun 14, 2023 •

edited

Loading

xmnlab Jun 16, 2023 •

edited

Loading