Some docs cleanup #194

bollwyvl · 2020-02-11T02:23:16Z

References

bumps the frontend architecture to reflect the changes from Refactor LSPConnection, ConnectionManager #165
some things missing from Start sphinx docs #177, like how to build the docs

Code changes

travis
- 3.8 (not -dev)
- ~~add 3.9-dev~~
  - still getting the odd ModuleNotFoundError: No module named 'pip'

User-facing changes

Some more progress towards getting the docs usable, fixing links, etc.

Backwards-incompatible changes

N/A

Chores

linted
tested
documented
changelog entry

bollwyvl · 2020-02-11T12:47:34Z

Actually got the link checker wired up and passing locally... once this works in CI, that's probably a good place to stop!

bollwyvl · 2020-02-12T01:31:43Z

LGTM

krassowski · 2020-02-12T03:46:36Z

docs/EXTENDING.md

@@ -13,7 +13,7 @@
 Language Server Specs can be [configured](./LANGUAGESERVERS.md) by Jupyter users,
 or distributed by third parties as python or JSON files. Since we'd like to see
 as many Language Servers work out of the box as possible, consider
-[contributing a spec](../CONTRIBUTING.md#specs), if it works well for you!
+[contributing a spec](../CONTRIBUTING.ipynb#specs), if it works well for you!


Confused by this...

krassowski · 2020-02-12T03:46:42Z

docs/LANGUAGESERVERS.md

@@ -42,12 +42,12 @@ tested to work with `jupyter-lsp`.
 Don't see an implementation for the language server you need? You can
 [bring your own language server](#adding-custom-language-servers).

-> Please consider [contributing your language server spec](../../CONTRIBUTING.md#spec)
+> Please consider [contributing your language server spec](../Contributing.md)


krassowski · 2020-02-12T03:46:51Z

docs/LANGUAGESERVERS.md


 `pip`-installable packages in the same environment as the Jupyter `notebook` server
 can be automatically detected as providing a language server spec. These are a
-little more involved: see [CONTRIBUTING](../../CONTRIBUTING.md).
+little more involved: see [CONTRIBUTING](Contributing.md).


krassowski · 2020-02-12T03:47:49Z

docs/conf.py


 html_context = {
-    "display_github": True,
+    "display_github": False,


IMO worth turning on (not necessarily in this PR)

krassowski · 2020-02-12T03:50:39Z

Looks good in general, just want to get a confirmation about the paths to Contributing. By my intuition, at least one of them is must be wrong (but I can be wrong too!).

bollwyvl · 2020-02-12T12:36:55Z

All of the above are link-checker-driven-development artifacts, whoops:

i think i can fix all the internal links: (nb)sphinx is strangely passive aggressive about file extensions, in that sometimes it doesn't even care which you use, and sometimes gets very angry
- might end up rewriting more markdown getting passed through to notebooks, or see if i can get rid of the wrappers altogether (preferable)
the github link creates links on generated pages that don't exist, like search and genindex
- i'll look into not showing those on those specific pages

bollwyvl · 2020-02-15T03:11:12Z

Well, that ended up being a bit more work than i was hoping, but it's feeling better:

fixed the the search and genindex github links
- ...rather brutally by forking the template (ignored by prettier)
moved all the docs content into notebooks
generate the language server tables directly from a hot manager instance 🎉
- requires doing the full yarn and python install, but we'll KNOW the docs are right (if they build)

I guess at this point with as much content in there as there is, it may well be worth it to grab some of the stuff from prenotebook as part of lint.py:

black/isort the python code cells
prettier the markdown
strip the outputs/execution numbers

bollwyvl · 2020-02-15T04:46:13Z

docs/_templates/breadcrumbs.html

+    {% endblock %}
+    {% block breadcrumbs_aside %}
+      <li class="wy-breadcrumbs-aside">
+        {% if hasdoc(pagename) and pagename not in ["search", "genindex"] %}


all for this line...

krassowski · 2020-02-16T15:33:50Z

README.md

@@ -4,11 +4,11 @@

 > _This project is still maturing, but you are welcome to check it out, leave feedback and/or a PR_

-Quick Links: **[Installation](#installation) | [Language Servers](./docs/LANGUAGESERVERS.md) | [Updating](#updating) | [Changelog](./CHANGELOG.md) | [Roadmap](./docs/ROADMAP.md) | [Contributing](./CONTRIBUTING.md) | [Extending](./docs/EXTENDING.md)**
+Quick Links: **[Installation](./Installation.ipynb) | [Configuring](./docs/Configuring.ipynb) | [Updating](#updating) | [Changelog](./CHANGELOG.md) | [Roadmap](./docs/Roadmap.ipynb) | [Contributing](./CONTRIBUTING.md) | [Extending](./docs/Extending.ipynb)**


./docs/Installation.ipynb ? Actually, I would probably prefer to have this go to the short version of the installation within README (we can shorten it) and then to have a link to the notebook from here.

In the quick links we maybe could have something like: Installation: [Basic](#installation) | [Full](notebook) (but I am not full convinced)

agreed, README.md needs to pretty much be standalone for the 80% case. Hopefully fixed now.

bollwyvl · 2020-02-18T01:12:38Z

Thanks for the review, looking into it now...

bollwyvl · 2020-02-18T01:27:14Z

Probably best if this lands prior to #199 so that i can fix up changelog and extending while it's still fresh in my mind... so many moving pieces.

krassowski · 2020-02-22T17:22:57Z

We will need to do something about these Linux/Docker failures...

krassowski · 2020-02-22T17:25:17Z

README.md

+   ```bash
+   conda install -c conda-forge nodejs
+   # or one of the following, as an administrator
+   choco install nodejs            # Windows with Chocolatey


if it is all in one block, I am 100% sure some users will just copy-paste it all. I would move these examples to the docs.

krassowski · 2020-02-22T17:26:29Z

README.md

+   ```bash
+   conda install -c conda-forge python=3
+   # or
+   conda install -c conda-forge jupyterlab=1.2


bollwyvl added 8 commits February 10, 2020 21:18

some docs cleanup after jupyter-lsp#165 and jupyter-lsp#177 landed

903844b

linting

e1b2f09

[travis] use 3.8, 3.9-dev

8d09b05

pull back 3.9, still has weird pip error

b0f2312

redirect some mork markdown through ipynb for links

e84e8a3

point 0.6.0 (unreleased) at 0.6.1

a4c3afb

some more url fixes

7010aa9

add pytest-check-links

ab7041d

bollwyvl changed the title ~~[wip] Some docs cleanup~~ Some docs cleanup Feb 11, 2020

docs for link checking, only test internal links in CI

1afd55f

bollwyvl requested a review from krassowski February 12, 2020 01:31

krassowski reviewed Feb 12, 2020

View reviewed changes

bollwyvl added 7 commits February 14, 2020 21:33

significant work on docs, renaming, server metadata

3986b98

linting

1f7b5e0

fix some more links

95a21f9

link checking

e8a5e70

link checking

3e5b397

link checking

dac6927

clobber broken github link on search/genindex, sort prettierignore

9e8f408

bollwyvl added 3 commits February 14, 2020 23:10

format notebooks

07d77b3

also strip empty cells (didn't have any, apparently)

1d11c82

fix typo in docs ci

de13ae0

bollwyvl commented Feb 15, 2020

View reviewed changes

update some tested install docs, make github skipping less janky

f900f7a

krassowski reviewed Feb 16, 2020

View reviewed changes

some more install work

85e1f65

bollwyvl closed this Feb 18, 2020

bollwyvl reopened this Feb 18, 2020

bollwyvl closed this Feb 19, 2020

bollwyvl reopened this Feb 19, 2020

krassowski closed this Feb 22, 2020

krassowski reopened this Feb 22, 2020

krassowski merged commit 685504d into jupyter-lsp:master Feb 22, 2020

krassowski reviewed Feb 22, 2020

View reviewed changes

README.md

```bash

conda install -c conda-forge python=3

# or

conda install -c conda-forge jupyterlab=1.2

Copy link

Member

krassowski Feb 22, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

?

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Some docs cleanup #194

Some docs cleanup #194

bollwyvl commented Feb 11, 2020 •

edited

Loading

bollwyvl commented Feb 11, 2020

bollwyvl commented Feb 12, 2020

krassowski Feb 12, 2020

bollwyvl Feb 15, 2020

krassowski Feb 12, 2020

bollwyvl Feb 15, 2020

krassowski Feb 12, 2020

bollwyvl Feb 15, 2020

krassowski Feb 12, 2020

bollwyvl Feb 15, 2020

krassowski commented Feb 12, 2020

bollwyvl commented Feb 12, 2020

bollwyvl commented Feb 15, 2020

bollwyvl Feb 15, 2020

krassowski Feb 16, 2020

bollwyvl Feb 18, 2020

bollwyvl commented Feb 18, 2020

bollwyvl commented Feb 18, 2020

krassowski commented Feb 22, 2020

krassowski Feb 22, 2020

krassowski Feb 22, 2020

Some docs cleanup #194

Some docs cleanup #194

Conversation

bollwyvl commented Feb 11, 2020 • edited Loading

References

Code changes

User-facing changes

Backwards-incompatible changes

Chores

bollwyvl commented Feb 11, 2020

bollwyvl commented Feb 12, 2020

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

krassowski commented Feb 12, 2020

bollwyvl commented Feb 12, 2020

bollwyvl commented Feb 15, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bollwyvl commented Feb 18, 2020

bollwyvl commented Feb 18, 2020

krassowski commented Feb 22, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bollwyvl commented Feb 11, 2020 •

edited

Loading