Minor docs updates

[mwcraig]

This PR:

• Updates the documentation requirements.
• Temporarily fixes Documentation notebook output duplicated #2629 by pinning the version of nbsphinx to 0.4. The duplication reported in Documentation notebook output duplicated #2629 is happening because nbsphinx 0.5 introduced a new feature, storing the widget in the notebook, so now both jupyter_sphinx and nbsphinx are generating the widget.
• Fixes Password missing from documentation #1747 by adding documentation of the password widget
• Fixes broken link in documentation #2625 (broken link)
• Fixes another broken link reported by sphinx.

[pbugnion]

This looks great! I think the clarification on the password widget is useful.

This needs to be rebased off Jason's PR (#2668) that bumps nbformat on the example notebooks to avoid build errors. For reference, I tried this here and had no issues.

[jtpio]

How about also renaming the name of the conda environment to ipywidgets_docs (with a s) for consistency?

[mwcraig]

The environment is renamed; it looks like #2660 covers similar ground -- should I pull in some of those changes here? Or merge #2660 and then rebase?

[pbugnion]

My preference would be on merging this independently of #2660 to avoid coupling the two, since there are still open unresolved questions on #2660.

[mwcraig]

I'll address the maps question over there, but #2660's solution to the double-widgets problem is definitely better than this one, so we'll want to incorporate that in some way.

[mgeier]

You can simply drop the file extension to fix the link.

Sphinx document names don't include a file suffix.

http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-doc

[mwcraig]

Thanks; several of your fixes in #2660 are more elegant than what is in here...

[pbugnion]

@mwcraig I think the only thing still relevant in this PR is the password documentation?

[mwcraig]

@pbugnion -- there are a few minor things which should be more apparent in this rebase. Ordering the dependencies alphabetically is a little...odd...but makes it easier to catch duplicate package names.

[pbugnion]

@mwcraig thanks for clarifying and for pushing this through!

It's probably worth noting that the docs don't build with conda (see PR #2708 ), so I'm not sure whether it's worth fixing the requirements here?

We could merge just the password change and the broken link and hold off on the requirements fix until #2708 is merged?

[mgeier]

Why are you adding jupyter_sphinx again (which I meticulously removed in #2660)?

And BTW, alphabetic order is great!
Unless that makes a difference for conda's dependency resolution algorithm?

[mwcraig]

Why are you adding jupyter_sphinx again (which I meticulously removed in #2660)?

Apparently alphabetical order wasn't as useful as I thought because I skimmed right over it, need better 👓. Will remove in a moment.

[mwcraig]

@pbugnion -- I don't have strong feelings about the conda fix; I was building the environment locally to test but it is honestly a hassle because you have to install the dev version of ipywidgets into this separate environment after you create it.

I'm going to push the removal of jupyter_sphinx here so that is done.

Then 2 options, you choose:

1. Merge this as-is, rebase Switch installing documentation dependencies to pip #2708. Update dev docs instructions in Switch installing documentation dependencies to pip #2708 to drop the conda environment stuff.
2. Do only the notebook fixes here, drop jupyter_sphinx in Switch installing documentation dependencies to pip #2708. Update dev docs instructions in Switch installing documentation dependencies to pip #2708 to drop the conda environment stuff.

I can do either of these but just need to know the preferred route. Either way we end up at correct documentation and simplified requirements.

[pbugnion]

Looks great! I vote for 1 -- merging as is and rebasing 2708.

Happy to merge when you're ready!

[jasongrout]

Merged in master.

[jasongrout]

Thanks!