Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update and fix docs #354

Merged
merged 9 commits into from
Aug 18, 2022
Merged

Update and fix docs #354

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
17f9817
language = en, check_meta = True
gabalafou Aug 17, 2022
2f85e4e
typedoc updates
gabalafou Aug 18, 2022
463d164
conf.py changes
gabalafou Aug 18, 2022
ea6e013
fix edit on github urls
gabalafou Aug 18, 2022
5ec144a
remove bypass to build api, examples
gabalafou Aug 18, 2022
63db605
remove indices and tables
gabalafou Aug 18, 2022
7528b77
no more display_github
gabalafou Aug 18, 2022
be662a5
forgot to remove api_index.html file
gabalafou Aug 18, 2022
919393d
remove tsconfigdoc.json
gabalafou Aug 18, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
github_url: 'https://github.com/jupyterlab/lumino/blob/main/CHANGELOG.md'
---

# Changelog

<!-- <START NEW CHANGELOG ENTRY> -->
Expand Down
26 changes: 3 additions & 23 deletions docs/source/_templates/breadcrumbs.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,31 +10,11 @@
{% block breadcrumbs_aside %}
<li class="wy-breadcrumbs-aside">
{% if hasdoc(pagename) %}
{% if display_github %}
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Didn't see the point in this if-statement.

{% if check_meta and 'github_url' in meta %}
<!-- User defined GitHub URL -->
<a href="{{ meta['github_url'] }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
<!-- User defined GitHub URL -->
<a href="{{ meta['github_url'] }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
{% else %}
<a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode or "blob" }}/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
Copy link
Contributor Author

Choose a reason for hiding this comment

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

I didn't see the point in keeping all of this extra code for BitBucket and GitLab.

{% endif %}
{% elif display_bitbucket %}
{% if check_meta and 'bitbucket_url' in meta %}
<!-- User defined Bitbucket URL -->
<a href="{{ meta['bitbucket_url'] }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a>
{% else %}
<a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}/src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}{{ suffix }}?mode={{ theme_vcs_pageview_mode or "view" }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a>
{% endif %}
{% elif display_gitlab %}
{% if check_meta and 'gitlab_url' in meta %}
<!-- User defined GitLab URL -->
<a href="{{ meta['gitlab_url'] }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a>
{% else %}
<a href="https://{{ gitlab_host|default("gitlab.com") }}/{{ gitlab_user }}/{{ gitlab_repo }}/{{ theme_vcs_pageview_mode or "blob" }}/{{ gitlab_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a>
{% endif %}
{% elif show_source and source_url_prefix %}
<a href="{{ source_url_prefix }}{{ pagename }}{{ suffix }}">{{ _('View page source') }}</a>
{% elif show_source and has_source and sourcename %}
<a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow"> {{ _('View page source') }}</a>
<a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode or "blob" }}/{{ github_version | replace("origin/", "") }}{{ conf_py_path }}{{ pagename }}{{ page_source_suffix }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
{% endif %}
{% endif %}
</li>
Expand Down
208 changes: 0 additions & 208 deletions docs/source/api_index.html
View file
Open in desktop

This file was deleted.

64 changes: 25 additions & 39 deletions docs/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
language = 'en'
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Sphinx was emitting a warning about language being None.


# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
Expand All @@ -104,56 +104,43 @@ def build_api_docs(out_dir):
docs = osp.join(HERE, os.pardir)
root = osp.join(docs, os.pardir)
docs_api = osp.join(docs, "source", "api")
api_index = osp.join(docs_api, "algorithm", "index.html")

if osp.exists(api_index):
# avoid rebuilding docs because it takes forever
# `make clean` to force a rebuild
Copy link
Contributor Author

Choose a reason for hiding this comment

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

This didn't actually work because make clean only removes files from the build/ directory. But this code was checking the source/ directory.

This compilation-bypass was basically copied from the JupyterLab repo, but the JupyterLab repo adds additional work to make clean.

I don't think building the docs and examples for Lumino take that long, so I just decided to remove the bypass for simplicity (here and examples below).

print(f"already have {api_index}")
else:
print("Building lumino API docs")
npm = [shutil.which('npm')]
check_call(npm + ['install', '-g', 'yarn'], cwd=root)
yarn = [shutil.which('yarn')]
check_call(yarn, cwd=root)
check_call(yarn + ["docs"], cwd=root)

print("Building lumino API docs")
npm = [shutil.which('npm')]
check_call(npm + ['install', '-g', 'yarn'], cwd=root)
yarn = [shutil.which('yarn')]
check_call(yarn, cwd=root)
check_call(yarn + ["docs"], cwd=root)

dest_dir = osp.join(out_dir, "api")
print(f"Copying {docs_api} -> {dest_dir}")
if osp.exists(dest_dir):
shutil.rmtree(dest_dir)
shutil.copytree(docs_api, dest_dir)
shutil.copy(osp.join(HERE, 'api_index.html'), osp.join(dest_dir, 'index.html'))
Copy link
Contributor Author

Choose a reason for hiding this comment

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

If we set readme to none in the Typedoc config file then we don't need to do this copy step.


# build js examples and stage them to the build directory
def build_examples(out_dir):
"""build js example docs"""
docs = osp.join(HERE, os.pardir)
root = osp.join(docs, os.pardir)
examples_dir = osp.join(docs, "source", "examples")
example_index = osp.join(examples_dir, EXAMPLES[0], "index.html")

if osp.exists(example_index):
# avoid rebuilding examples because it takes forever
# `make clean` to force a rebuild
print(f"already have examples")
else:
print("Building lumino examples")
npm = [shutil.which('npm')]
check_call(npm + ['install', '-g', 'yarn'], cwd=root)
yarn = [shutil.which('yarn')]
check_call(yarn, cwd=root)
check_call(yarn + ["build"], cwd=root)
check_call(yarn + ["build:examples"], cwd=root)

# Copy the examples into source so the JS files get picked up
for example in EXAMPLES:
source = osp.join(root, "examples", f"example-{example}")
dest_dir = osp.join(docs, "source", "examples", example)
print(f"Copying {source} -> {dest_dir}")
if osp.exists(dest_dir):
shutil.rmtree(dest_dir)
shutil.copytree(source, dest_dir)

print("Building lumino examples")
npm = [shutil.which('npm')]
check_call(npm + ['install', '-g', 'yarn'], cwd=root)
yarn = [shutil.which('yarn')]
check_call(yarn, cwd=root)
check_call(yarn + ["build"], cwd=root)
check_call(yarn + ["build:examples"], cwd=root)

# Copy the examples into source so the JS files get picked up
for example in EXAMPLES:
source = osp.join(root, "examples", f"example-{example}")
dest_dir = osp.join(docs, "source", "examples", example)
print(f"Copying {source} -> {dest_dir}")
if osp.exists(dest_dir):
shutil.rmtree(dest_dir)
shutil.copytree(source, dest_dir)

dest_dir = osp.join(out_dir, "examples")
print(f"Copying {examples_dir} -> {dest_dir}")
Expand Down Expand Up @@ -198,7 +185,6 @@ def build_examples(out_dir):

# Output for github to be used in links
html_context = {
"display_github": True, # Integrate GitHub
"github_user": "jupyterlab", # Username
"github_repo": "lumino", # Repo name
"github_version": "main", # Version
Expand Down
7 changes: 0 additions & 7 deletions docs/source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,3 @@ Lumino
api
examples
migration

Indices and tables
Copy link
Contributor Author

Choose a reason for hiding this comment

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

These links come from the Sphinx getting started template, but they're not useful for this repo.

==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
3 changes: 2 additions & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@
"clean:examples": "lerna run clean --scope \"@lumino/example-*\"",
"clean:src": "lerna run clean --scope \"@lumino/!(test-|example-)*\"",
"clean:tests": "lerna run clean:tests",
"docs": "rimraf docs/source/api && lerna run build:src --concurrency 1 && lerna run docs",
Copy link
Contributor Author

Choose a reason for hiding this comment

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

No need to remove docs/source/api, Typedoc already takes care of this.

"predocs": "lerna run build:src",
"docs": "typedoc",
"eslint": "eslint --ext .js,.jsx,.ts,.tsx --cache --fix .",
"eslint:check": "eslint --ext .js,.jsx,.ts,.tsx --cache .",
"get:dependency": "get-dependency",
Expand Down
5 changes: 4 additions & 1 deletion packages/algorithm/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@
"build:test": "tsc --build tests && cd tests && webpack",
"clean": "rimraf ./lib && rimraf *.tsbuildinfo && rimraf ./types && rimraf ./dist",
"clean:test": "rimraf tests/build",
"docs": "typedoc --options ../../typedoc.js src",
Copy link
Contributor Author

Choose a reason for hiding this comment

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

I decided to get rid of the docs script in each individual package because it doesn't really make sense to me to build the docs for a single package in isolation of the others, especially since some of them depend on others in the monorepo.

Please let me know if my reasoning here is wrong.

"minimize": "terser dist/index.js -c -m --source-map \"content='dist/index.js.map',url='index.min.js.map'\" -o dist/index.min.js",
"test": "npm run test:firefox-headless",
"test:chrome": "cd tests && karma start --browsers=Chrome",
Expand All @@ -39,6 +38,10 @@
"test:ie": "cd tests && karma start --browsers=IE",
"watch": "tsc --build --watch"
},
"typedoc": {
"entryPoint": "./src/index.ts",
"displayName": "algorithm"
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Without setting display name like this, the breadcrumbs in the rendered docs end up looking like: @lumino / @lumino/algorithm / member. You'll have to check the rendered docs, and see for yourself if you like it prefer it this way or not.

},
"devDependencies": {
"@microsoft/api-extractor": "^7.6.0",
"@rollup/plugin-node-resolve": "^13.3.0",
Expand Down
Loading