set up sphinx doc #138

marcobarilari · 2020-10-25T14:09:34Z

No description provided.

pep8speaks · 2020-10-25T14:09:37Z

Hello @marcobarilari! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

There are currently no PEP 8 issues detected in this Pull Request. Cheers! 🍻

Comment last updated at 2020-10-31 19:23:08 UTC

codecov · 2020-10-25T14:12:49Z

Codecov Report

Merging #138 into dev will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##              dev     #138   +/-   ##
=======================================
  Coverage   21.63%   21.63%           
=======================================
  Files          55       55           
  Lines         795      795           
=======================================
  Hits          172      172           
  Misses        623      623

Flag	Coverage Δ
unittests	`21.63% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0b51544...19fd82f. Read the comment docs.

marcobarilari · 2020-10-25T14:40:08Z

Hey @Remi-Gau, I followed the instructions in the spm pipeline repo and something happened but I have no idea about I am doing and if it is working. Sphinx is still very unclear to me

Remi-Gau · 2020-10-25T15:43:45Z

Are you saying you can't figure out the riddles that Sphinx is throwing you?
I guess they have chosen the name correctly.

Will have a look right away.

Remi-Gau · 2020-10-25T15:59:11Z

docs/.readthedocs.yml0

@@ -0,0 +1,26 @@
+# .readthedocs.yml


Not sure why you have several .readthedocs.yml files in the docs folder.

As long as you have one in the root folder, you are good to go.

Also the read the docs part comes later and is only to use the website "read the docs" to display the documentation on line. So this is not purely "sphinx" related.

For example "read the docs" can also render docs written with "mkdocs".

Remi-Gau · 2020-10-25T16:03:18Z

docs/source/conf.py

+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os


You are going to need to uncomment those.

You also need to modify the path in os.path.abspath so it points to the root of this repo.

You can just do like in conf.py of the CPP_SPM repo

I did change these parts but I suspect I made a mistake and ignore the changes while committing. My bad

docs/source/conf.py

docs/source/index.rst

Remi-Gau · 2020-10-25T16:17:38Z

Looks like you are on good track to me.

You need to make some changes to the conf.py.

Once you are done you can try to build the doc with the following command: to run from within the docs folder.

sphinx-build -b html source build

This creates a set of html file in the build folder you can use to view and browse the doc.

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

Remi-Gau · 2020-10-25T16:23:46Z

Also looking around to other repo that use Sphinx it seems that we do not need to commit the content of the build folder as read the docs will take care of building the docs. (I am also trying to figure this out).

So you can remove all that of that from the repo and add the build folder to .gitignore

Remi-Gau · 2020-10-25T16:27:50Z

Oh by the way you can add several comments at once through the github graphic interface.

I learnt that on the BIDS specs and I still to update their doc there to help others with this.
bids-standard/bids-specification#633 (comment)

marcobarilari · 2020-10-25T16:37:26Z

ok, I have rebuild sphinx doc with the new config.py edits and add the build folder to .gitignore

…hinx-docs

marcobarilari · 2020-10-31T15:53:44Z

docs/source/function_description.rst

+
+.. autofunction:: initPTB()
+
+:func:`initPTB`


I don't understand this part, what is it the point to have :func:initPTB`` and .. autofunction:: getExperimentStart after it?

Suggested change

:func:`initPTB`

You are right: this one can be removed and autofunction getExpStart brought up. :-)

marcobarilari · 2020-10-31T16:19:05Z

I have added all the function in the function_description.rst file LMK if looks ok and what's next (apart from making it nicer :) )

Remi-Gau · 2020-10-31T16:50:35Z

I have added all the function in the function_description.rst file LMK if looks ok and what's next (apart from making it nicer :) )

I think you can try using the read the docs website to build the docs so we then have an online version.

If you feel like it.

marcobarilari · 2020-10-31T17:14:54Z

sure, but somehow the sphinx updates should be in a branch (master) of the repo, shouldn't they? Or there is a way to build the rtd from a PR?

Remi-Gau · 2020-10-31T17:38:25Z

If it builds locally you can merge this into dev. Then on the read the docs (RTD) in the advanced settings you can set the default branch to build the doc from.

See here: https://readthedocs.org/dashboard/cpp-bids-spm/advanced/

Let me know if you can't access I might need to add you as Maintainers on RTD.

You can also start transferring some content from the old markdown index.md to the rst files if you want. In this PR before merging and trying to build with RTD or in another PR. Up to you. 🚀

marcobarilari · 2020-10-31T17:48:38Z

See here: https://readthedocs.org/dashboard/cpp-bids-spm/advanced/

I see this (lol)

        \          SORRY            /
         \                         /
          \    This page does     /
           ]   not exist yet.    [    ,'|
           ]                     [   /  |
           ]___               ___[ ,'   |
           ]  ]\             /[  [ |:   |
           ]  ] \           / [  [ |:   |
           ]  ]  ]         [  [  [ |:   |
           ]  ]  ]__     __[  [  [ |:   |
           ]  ]  ] ]\ _ /[ [  [  [ |:   |
           ]  ]  ] ] (#) [ [  [  [ :===='
           ]  ]  ]_].nHn.[_[  [  [
           ]  ]  ]  HHHHH. [  [  [
           ]  ] /   `HH("N  \ [  [
           ]__]/     HHH  "  \[__[
           ]         NNN         [
           ]         N/"         [
           ]         N H         [
          /          N            \
         /           q,            \
        /                           \

Remi-Gau · 2020-10-31T18:06:41Z

oh dear...

Tried to add you using your github username.

Let me know if this works

marcobarilari · 2020-10-31T18:07:41Z

it worked! thank you

marcobarilari · 2020-10-31T19:25:04Z

All right, I added an installation section (also to try sphynx synstax) and going to merge this and publish it to see if it works.

Will add more docs in the future in other PRs, LMK

set up basic environment for sphinx doc

5eb0b56

marcobarilari marked this pull request as draft October 25, 2020 14:09

marcobarilari added 2 commits October 25, 2020 15:27

build doc locally

f5e9bcf

add readthedocs yml files

782ac71

Remi-Gau requested changes Oct 25, 2020

View reviewed changes

docs/source/index.rst Outdated Show resolved Hide resolved

marcobarilari and others added 8 commits October 25, 2020 17:18

Update docs/source/conf.py

3a0844b

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

Update docs/source/conf.py

966b852

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

Update docs/source/conf.py

47c03f4

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

Update docs/source/conf.py

759662e

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

Update docs/source/conf.py

e7d75e3

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

Update docs/source/conf.py

f38b7bc

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

Update docs/source/conf.py

b208cd8

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

Update docs/source/index.rst

83461e4

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

re build sphinx doc

b52733c

marcobarilari and others added 7 commits October 25, 2020 17:41

CI md fix

f4cf18c

CI md fix 2

9dd8cb5

ignore files defined by virtual env

3671580

CI fix 3

84ef912

Merge remote-tracking branch 'origin/marco_sphinx-docs' into marco_sp…

de17a47

…hinx-docs

remove content of the build folder

6276d1f

fix extra space in index

f4a8c72

Remi-Gau and others added 2 commits October 25, 2020 18:49

add some demo for cpp ptb functions and those in subfolders

2e901af

add function list in src

e47f8dd

marcobarilari commented Oct 31, 2020

View reviewed changes

add all the function to sphinx function description

c49eb8f

fix contenents

8a4043f

marcobarilari added 2 commits October 31, 2020 19:24

add installation

449adac

make installation section nicer

19fd82f

marcobarilari marked this pull request as ready for review October 31, 2020 19:25

marcobarilari merged commit ac0f03b into cpp-lln-lab:dev Oct 31, 2020

set up sphinx doc #138

set up sphinx doc #138

Uh oh!

Conversation

marcobarilari commented Oct 25, 2020

Uh oh!

pep8speaks commented Oct 25, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Comment last updated at 2020-10-31 19:23:08 UTC

Uh oh!

codecov bot commented Oct 25, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

marcobarilari commented Oct 25, 2020

Uh oh!

Remi-Gau commented Oct 25, 2020

Uh oh!

Remi-Gau Oct 25, 2020

Choose a reason for hiding this comment

Uh oh!

Remi-Gau Oct 25, 2020

Choose a reason for hiding this comment

Uh oh!

marcobarilari Oct 25, 2020

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Remi-Gau commented Oct 25, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Remi-Gau commented Oct 25, 2020

Uh oh!

Remi-Gau commented Oct 25, 2020

Uh oh!

marcobarilari commented Oct 25, 2020

Uh oh!

marcobarilari Oct 31, 2020

Choose a reason for hiding this comment

Uh oh!

Remi-Gau Oct 31, 2020

Choose a reason for hiding this comment

Uh oh!

marcobarilari commented Oct 31, 2020

Uh oh!

Remi-Gau commented Oct 31, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

marcobarilari commented Oct 31, 2020

Uh oh!

Remi-Gau commented Oct 31, 2020

Uh oh!

marcobarilari commented Oct 31, 2020

Uh oh!

Remi-Gau commented Oct 31, 2020

Uh oh!

marcobarilari commented Oct 31, 2020

Uh oh!

marcobarilari commented Oct 31, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

pep8speaks commented Oct 25, 2020 •

edited

Loading

codecov bot commented Oct 25, 2020 •

edited

Loading

Remi-Gau commented Oct 25, 2020 •

edited

Loading

Remi-Gau commented Oct 31, 2020 •

edited

Loading