Rise: documentation on customization

[parmentelat]

IIMHO the structure of this page here can be improved
https://damianavila.github.io/RISE/customize.html

I suggest 3 parts

1. how to customize config. variables (using javascript, using python, mention the trick with jupyter --paths)
2. what : the list of available settings, their possible values, and effects
3. keyboard : list of actions as exposed to Jupyter keybindings system, their default binding when relevant

optionnally the last part could be made a separate section, of course

PS. as a side note I must add that I am not at all comfortable with this RST thing (to state things politely;) How about moving to markdown instead ?

[damianavila]

I suggest 3 parts

Good suggestions.

How about moving to markdown instead ?

I am OK with that.

[parmentelat]

just wanted to add a pointer to #297 that has some valuable information, particularly about jupyter --paths that could be mentioned in the first section

[choldgraf]

I recommend writing a customization section that's similar to how sphinx-gallery wrote theirs:

https://sphinx-gallery.readthedocs.io/en/stable/advanced_configuration.html

[karelin]

@parmentelat I personally believe it is better to stay with RST for Python-related projects.

[parmentelat]

I can agree that RST has a more accurate syntax and allows for more sophistication, but this comes at the price of a horrible syntax, that I personnally find impossible to remember.

OTOH markdown is all over the place - here on github to start with - and it's simple, so easy to remember.

Given the needs of this specific project, I do not feel like there is anything that we would need that markdown would not support.

So @karelin can you please elaborate ?

[karelin]

My point is as follows: if RISE will remain mainly JavaScript project, migration to Markdown is quite reasonable. But, if more Python code is expected, with necessity to document API, RST format is way much better, as it is compatible with Python docstrings, providing single-source documentation for API.

Additionally, RST format does not go alone: it is accompanied by Sphinx library, extending its capabilities and providing ready scripts to generate multiple output formats. And if one have Anaconda installed, Sphinx is already included.

IMO, at current size and state of RISE, particular documentation format can be chosen just according to contributors taste.

[parmentelat]

Thanks for the clarification; as you said RISE is primarily a javascript project at this point

plus, sphinx does not only support RST, there are a lot of valuable alternatives for docstrings within the spinx ecosystem like e.g. numpy style or google style, that do not rely on RST; I feel like I am not alone out there being repelled by the RST syntax ;)

In addition the project already has a bit of markdown, if only the readme, so IMHO it would not feel like totally off to move to markdown. This being said, it will take some time indeed, so it probably won't happen tomorrow morning :)

[choldgraf]

FWIW, it looks like this issue has kind of devolved into a "markdown vs rst" debate. IMO that is _far less important_ than having the content about customization up there in the first place, and should not be blocking on that addition. Just pick something, the website probably won't become so unwieldy that switching if necessary will be that much work...

[parmentelat]

to clarify, the issue has gone cold more out of a lack of time than anything else, the format is not the problem here :)

there might be some confusion though on the initial scope of the issue; the point was more to redesign the entire page on customization than to add details on the latest settings that were introduced with last release - if that's what you're asking

about that, having heavily customized my own environment, I'm unsure about the default values in place right now. I think I remember that auto_select=code is not presently the default setting, but was kind of hoping that it could be adopted as the default setting after some time, which IMHO could essentially make the need for documentation far less stringent

finally the plan was also to document the keyboard actions, which is a matter pending as per #306

all this admittedly make the issue much larger than what you might be after, and if I'm right please feel free to submit a PR to address your specific needs

[choldgraf]

I bit off a chunk about adding more structured customization docs here: #318

that should get us started w/ a general structure, though the content itself probably still needs updating.

[damianavila]

the format is not the problem here :)

We all agree.

that should get us started w/ a general structure,

Great! I have already reviewed and merge that PR

though the content itself probably still needs updating.

@choldgraf are you planning to push more PRs related with this? In that case, I will not close this one so we can keep discussing and referencing any new PRs/ideas.

[choldgraf]

@damianavila the main thing remaining is to make sure that the list documented there is complete. It's hard for me to do that on my own. In the PR that you just merged did that seem like enough?

[damianavila]

In the PR that you just merged did that seem like enough?

Yep, it has the main things. @parmentelat you started this thread, what do you think? What would you like to add?

[parmentelat]

I'd like to comment on the general topic of documentation, trying to summarize where we are and we could go from here. I guess there are several dimensions

Where to find the doc: it looks like it is exposed on at least 2 locations

• I first ran into https://damianavila.github.io/RISE/ which is referenced from the github readme
• but there is also this here http://rise.readthedocs.io/en/stable/

I haven't checked thoroughly but it feels like they are both out-dated in a different way:

• the former (github pages) mentions 5.1.0 and my understanding is, it is based on the gh-pages branch, which involves some complexity of its own;
• the latter (readthedocs) was updated for the last time more than 4 months ago as per https://readthedocs.org/projects/rise/builds/

To make things even worse, these also differ from the doc that I have generated locally on my mac with sphinx (this one has the pdf export section)

IMO It would make our life much easier if we could go to a model where the rtd instance was refreshed via webhooks upon each new commit pushed onto github - it would also remove the need for the rather complex/awkward process that deals with gh-pages as described in doc/README.md

What to find in the doc

The current contents is maybe not 100% complete, but imho the relevant sections are mostly there.
Here's a proposal for a revised plan

• installation

• usage - maybe add links to the youtube demo and mybinder if available

• customisation; since that was the original topic, I'd like to detail this one; I am assuming we go with the change about #309 & nbextensions_configurator

  • explain the config options;
  • explain differents levels : (a) for one user on his laptop ; (b) for one notebook wherever it runs (in the metadata)

  • explain how to change these 2 levels: (a) with python or nbextensions_configurator and (b) with the notebook-metadata editor

  • adding custom css

  • keyboard shortcuts, and more generally Jupyter actions

• I'd like to think about inserting somewhere (new section at this point ?) a list of related resources on the Internet:

  • github
  • readthedocs (if that's the choice)
  • gitter
  • mybinder ? I made an attempt at creating a mybinder image so that newcomers could have a quick glance; I am unsure if RISE is readily available under mybinder though - https://mybinder.org/v2/gh/damianavila/RISE/master?filepath=examples%2Fheader-footer.ipynb
  • the youtube links (the talk and the demo)

  Would it be OK if the talk does not have a section on its own and only shows up as one bullet/subsection here




• PDF Export




• Changelog




• Developer doc

---

If this sounds like a plan, I can propose a PR to clean this all up; maybe even based on markdown if we're still OK with that general direction.

[choldgraf]

ah I didn't realize there were two different versions of the RISE docs out there - I agree there should definitely only be one

[parmentelat]

the thing is, I have write access neither on the github nor on the readthedocs ends

but this link http://docs.readthedocs.io/en/stable/webhooks.html#github explains how to set up peering once and for good; I use this for other projects and it's a real relief to stop having to worry about keeping the doc uptodate.

@damianavila currently only you have the rights to do that though, I would think.

[parmentelat]

this is only loosely related of course, but while I am at it:

the version number in the doc is hard-wired and not updated from the rest of the project, so it was lagging as still 5.1 in the doc; we might need an automated way to bump the version number globally;

[parmentelat]

@damianavila would you have somewhere the notebook used to record the gif about basic usage ?

[parmentelat]

@choldgraf
I was planning on having a link towards mybinder from the docs; it looks like I need to make it explicit that I require RISE in the mybinder image - which of course makes sense;

I think I remember you've done that before, do you know how I should go about doing that ?

thanks in advance

[choldgraf]

yep - see the "preparing your repo" section in the docs: https://mybinder.readthedocs.io/en/stable/using.html#preparing-a-repository-for-binder

and the RISE binder example repo:
https://github.com/binder-examples/jupyter-rise

for how to do it!

[parmentelat]

thanks, I could get that to work :)

I am currently crafting a new release for this doc thing; nowhere close to a PR yet but in case you're curious it's here
https://github.com/parmentelat/RISE/tree/doc2/doc

I have moved some parts of the doc to markdown, and for that reason I'll need at some point that the readthedocs project refers to doc/requirements.txt
It's probably not the case yet I guess since there is no such file yet in the repo, but if you get a chance to tweak this in the advanced settings it would be cool - alternatively if you prefer I can take over on the readthedocs admin task.

[damianavila]

AFAIR, I did not setup readthedocs, @choldgraf maybe? If not, we need to find who else setup that docs.

[parmentelat]

Yes it was @choldgraf indeed, I realize I should have made it more explicit that I was talking to him :)

[choldgraf]

whoah, it looks like it was me! hah I didn't remember doing that at all.

So what do people prefer? To use gh-pages or to use RTD? Benefit of RTD is that you get control over versioning etc and it should automatically get updated on latest. Benefit of gh-pages is that you get more flexibility over deployments.

[parmentelat]

as I mentioned it seems to me that rtd would be a better fit, as we could make the release process easier

it’s not as if we had plans for complex releases, or for maintaining several versions (which we could do just as well with rtd btw)

but I’m just a contributor, this is Damian’s call obviously

[choldgraf]

+1 to @parmentelat , seems reasonable to me to use RTD for this. @damianavila what do you think?

[damianavila]

Go for it guys! I agree in just one place to host the documentation and readthedocs seems a good fit.

[choldgraf]

👉 https://github.com/damianavila/RISE/pull/345 :-)

@damianavila you should turn off the github feature to serve the repo as a website, so there aren't two sites floating out there.

[choldgraf]

also @damianavila you should create an account on readthedocs so that you can administer !

[damianavila]

@choldgraf will do... and I will let you know when it is done. Please add @parmentelat as admin on that as well.

[choldgraf]

@permentelat do you have a readthedocs account? happy to add you as well

On Fri, Feb 16, 2018 at 12:40 PM Damian Avila [e-mail]
wrote:

@choldgraf https://github.com/choldgraf will do... and I will let you
know when it is done. Please add @parmentelat
https://github.com/parmentelat as admin on that as well.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/damianavila/RISE/issues/307#issuecomment-366352246,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ABwSHR7Pd-Q2S-v6Svkyb8um1urixthLks5tVefWgaJpZM4QQ-de
.

[parmentelat]

On 16 Feb 2018, at 21:43, Chris Holdgraf [e-mail] wrote:

@permentelat do you have a readthedocs account? happy to add you as well

yes my account is the same as here i.e. parmentelat

thanks

[choldgraf]

done! still waiting on Damian's name to be added

On Fri, Feb 16, 2018 at 12:44 PM parmentelat [e-mail]
wrote:

>

On 16 Feb 2018, at 21:43, Chris Holdgraf [e-mail]
wrote:

@permentelat do you have a readthedocs account? happy to add you as well

yes my account is the same as here i.e. parmentelat

thanks

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/damianavila/RISE/issues/307#issuecomment-366353229,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ABwSHeyVYPg5jzzuMj8znXbBviiEkF7Oks5tVei_gaJpZM4QQ-de
.

[parmentelat]

On 16 Feb 2018, at 23:25, Chris Holdgraf [e-mail] wrote:

done! still waiting on Damian's name to be added

thank you Chris

I will file a PR on my current work for the doc, and propose to use rtd as a showcase

[damianavila]

@damianavila you should turn off the github feature to serve the repo as a website, so there aren't two sites floating out there.

Will do that when we land the related PRs.

also @damianavila you should create an account on readthedocs so that you can administer !

My handle is damianavila at RTD.

[parmentelat]

damianavila now has write access on rtd

[parmentelat]

As a hopefully final comment on this one:

• I have reinstated the stable version in readthedocs, which is automatically maintained by the readthedocs infra to point at the highest tag

http://rise.readthedocs.io/en/stable/

• so now that 5.3.0 is out, I have changed all the issues that were referencing http://rise.readthedoc.io so that they all point at the stable version - as opposed to the latest version that I have been erroneously using at first

• I recommend that we always reference stable ; this way we won't have users reading the development doc, and thus believe they can use the features described there right away, like it happened a few times recently with the configurator and similar

[damianavila]

I have reinstated the stable version in readthedocs, which is automatically maintained by the readthedocs infra to point at the highest tag

Thanks for doing that!

so now that 5.3.0 is out, I have changed all the issues that were referencing http://rise.readthedoc.io so that they all point at the stable version - as opposed to the latest version that I have been erroneously using at first

Is that an upcoming PR?

I recommend that we always reference stable ; this way we won't have users reading the development doc, and thus believe they can use the features described there right away, like it happened a few times recently with the configurator and similar

I agree... I also set up the root url to point to stable. So if you hit http://rise.readthedocs.io, you will get the stable version.

Additionally, I have settled up the webhook, hopefully, it should work in the next pushes.

Time to close this one as well.

[parmentelat]

Non, not an upcoming PR, I made the changes directly in the github issues

[damianavila]

Ah... I asked because I think I saw some references in the source code to latest, IIRC.

[parmentelat]

As a matter of fact you're right, there are references in the git repo as well !

I could do that - and push it directly without a PR if that's all right with you;
what are precisely the plan for releasing 5.3.1 that you mentioned about the 2.7 / python_requires thingy ?
if this can be delayed for another day it seems quite doable to have that in 5.3.1

[damianavila]

what are precisely the plan for releasing 5.3.1 that you mentioned about the 2.7 / python_requires thingy ?

First, I want to get feedback from users because I do not know how many of them will be affected.

if this can be delayed for another day it seems quite doable to have that in 5.3.1

Sure, if you want to do a PR with the changes, we have time to review it and merge it before 5.3.1.

[damianavila]

parmentelat closed this in 4ab0437 4 hours ago

OK, I saw you already pushed the change. That's OK because is something self-contained.
But we can wait for 5.3.1 to deploy it. since now latest is the same as stable.