set up sphinx doc

[pep8speaks]

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! :beers:

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

[codecov[bot]]

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]

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]

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]

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.

[Remi-Gau]

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]

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. https://github.com/bids-standard/bids-specification/pull/633#issuecomment-713388002

[marcobarilari]

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

[marcobarilari]

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]

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]

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]

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. :rocket:

[marcobarilari]

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]

oh dear...

Tried to add you using your github username.

Let me know if this works

[marcobarilari]

it worked! thank you

[marcobarilari]

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