Skip to content

Commit

Permalink
Merge branch 'master' into master
Browse files Browse the repository at this point in the history
  • Loading branch information
ivanov authored Nov 17, 2023
2 parents 495b8a7 + 515ba5f commit 7404e45
Showing 221 changed files with 46,071 additions and 3,258 deletions.
5 changes: 5 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
blank_issues_enabled: false
contact_links:
- name: "\U0001FA90 Questions or issues about one of the tools in Jupyter"
url: https://discourse.jupyter.org
about: Welcome to the Jupyter meta repository! This repository is the home of the Jupyter-wide documentation. However, it is not the best place to ask questions about Jupyter. We recommend asking in the Jupyter community Discourse forum. Thanks!
22 changes: 22 additions & 0 deletions .github/ISSUE_TEMPLATE/doc_suggestion.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
---
name: "\U0001F4D6 Documentation suggestion"
about: Propose changes to the Jupyter-wide documentation

---
<!-- Thank you for contributing and welcome to the Jupyter meta repository!
This repository is the home of the Jupyter-wide documentation.
If you have a suggestion about possible changes to this documentation or
you just spotted something wrong, please report it here.
However, this is not the best place to ask questions about Jupyter.
If you have a question or an issue about one of the tools in Jupyter,
we recommend asking in the Jupyter community Discourse forum at the
link below:
https://discourse.jupyter.org
Thanks!
-->

41 changes: 41 additions & 0 deletions .github/workflows/release.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Build releases and (on tags) publish to PyPI
name: Release

# always build releases (to make sure wheel-building works)
# but only publish to PyPI on tags
on:
push:
pull_request:

jobs:
build-release:
runs-on: ubuntu-20.04
steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v2
with:
python-version: "3.10"

- name: install build package
run: |
pip install --upgrade pip
pip install build
pip freeze
- name: build release
run: |
python -m build --sdist --wheel .
ls -l dist
- uses: actions/upload-artifact@v3
with:
name: jupyter-${{ github.sha }}
path: "dist/*"
if-no-files-found: error

- name: publish to pypi
uses: pypa/gh-action-pypi-publish@v1.5.1
if: startsWith(github.ref, 'refs/tags/')
with:
user: __token__
password: ${{ secrets.pypi_password }}
15 changes: 15 additions & 0 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
version: 2

# Set the OS, Python version and other tools you might need
build:
os: ubuntu-22.04
tools:
python: "3.11"

# Build documentation in the "docs/" directory with Sphinx
sphinx:
configuration: docs/source/conf.py

python:
install:
- requirements: docs/doc-requirements.txt
54 changes: 45 additions & 9 deletions .travis.yml
Original file line number Diff line number Diff line change
@@ -1,12 +1,48 @@
language: python
sudo: false
python:
- 3.5
- 3.4
install:
- pip install --upgrade pip
- pip install --upgrade sphinx
- pip install jupyter_sphinx_theme
- pip install recommonmark
script:
- cd docs && make html
- 3.7

jobs:
include:
- stage: test-docs
install:
- pip install --upgrade pip sphinx
- pip install -r docs/doc-requirements.txt
script:
# Test build of HTML docs and English translation templates
- make -C docs html
- make -C docs gettext
- cd docs && sphinx-intl update -p build/locale -l en
- stage: push-tx
install:
- pip install --upgrade pip sphinx
- pip install -r docs/doc-requirements.txt
script:
- cd docs
# Rebuild HTML again to test for merge problems
- make html
# Regenerate English translation templates
- make gettext
- sphinx-intl update -p build/locale -l en
- git config --global user.email "travis@travis-ci.org"
- git config --global user.name "Travis CI"
# Stage any changes to the english source files
- git checkout master
- git add -A source/locale/en
- git status
# Commit the english templates, exiting early if there are no changes
- git commit -m '[ci skip] Update English source strings' || travis_terminate 0;
# Push the commit to master for Transifex to notice and update its strings for translation
- git remote add origin-tx https://${GH_TOKEN}@github.com/jupyter/jupyter.git
- git push -u origin-tx master

stages:
- name: test-docs
if: type = pull_request
- name: push-tx
if: type = push AND branch = master

env:
global:
secure: "xWn2cnWWNgtQEm9MXAIQerigtwkZxMDQYQnlbALvHywy63MVsWwvDSi9AnPm9ty+TuNxu8bWXGP99KNjSgPEkvb5wA/uCGmmD1l6eA8CdxWZeRVEQ88NNQMXvAwxmUEGub0OSBaLC37WHXWrM1BzPV9jXQGS5HKC1icu9en/ScorOnw7Waz1wfVpjZRPLbp/8+M5jadpp6VZfCp4rsAdb6wuBy0JKA383azPE8e87WBqDWCS3zR2esZqwJKkOpkMsTcIs+n6naJXFl9rmM5o+l4vEQ0aUpAzzdE2ZrX9HfwCuOAFGJmlYmdmCbNFty3Dh6vkdtZvp2ptysda6Tb2FFc1+5kWhzfrQoHBhkXQW9557YGjwmIohjCy7pmTxtucnd9JgqOUNH1dnvQ8Z4RMOTcIc1loKe80I903Yw4aFkj36gMWtMfqUghpEn1ZYbtl5k/ZWwTnRKyyg8bkFPU7EyXn+u97ItPMdIpRybXUa2qKWGohXoziDur/7ecJOiCI1ynJlUT8sJRa8fhpRd0/iTC28zECU3wa+G1nx4XcOowNX9tJAV4EpaL/DFNLXlxXfs1JX0Ccn0YTaljo/suOnINzBl1Dn87QDdYlvijFwmRrXWS363wjzp0K9OqqSWkfEAEuSBI6d4Ywc64Ob4+pRoBJIW3sT2LHNvP0yUQL39Y="
93 changes: 85 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -2,29 +2,106 @@

*Read this in other languages: [English](README.md), [Español](README.es-ES.md), [Português](README.pt-BR.md), [Français](README.fr-FR.md)*

Jupyter metapackage for installation and docs.
Jupyter metapackage for installation and documents

## Running the docs locally
First navigate to the `/docs` directory and create a `conda` environment:
## Documentation structure

This documentation uses the [Sphinx](https://sphinx-doc.org) documentation engine.

The documentation is located in the `docs/source` folder. When you build the documentation, it will be placed in the `docs/build` folder.
It is written in a combination of [reStructuredText](https://docutils.sourceforge.io/rst.html) and [MyST Markdown](https://myst-parser.readthedocs.io/).

## Build the documentation locally

There are a few ways to build the documentation; see below for instructions:

### Build the documentation automatically with `nox`

The easiest way to build the documentation locally is by using the [`nox` command line tool](https://nox.thea.codes/). This tool makes it easy to automate commands in a repository, and we have included a `docs` command to quickly install the dependencies and build the documentation.

To build and preview the site locally, follow these steps:

1. **Clone this repository**.

```console
$ git clone https://github.com/jupyter/jupyter
$ cd jupyter
```
2. **Install `nox`**

```console
$ pip install nox
```
3. **Run the `docs` command**

```console
$ nox -s docs
```

This will install the needed dependencies in a virtual environment using `pip`.
It will then place the documentation in the `docs/build/html` folder.
You may explore these HTML files in order to preview the site.

#### Create a live server to automatically preview changes

There is another `nox` command that will do the above, and also create a live server that watches your source files for changes, and auto-builds the website any time a change is made.

To start this live server, use the following `nox` command:

```console
$ nox -s docs-live
```

When the build is finished, go to the URL that is displayed. It should show a live preview of your documentation.

To stop serving the website, press **`Ctrl`**-`C` in your terminal

### Build the documentation manually

To build the documentation manually, follow these steps:

First, install [the `miniconda` Python distribution](https://conda.io/miniconda.html).

Next, navigate to the `/docs` directory and create a `conda` environment:

```bash
conda env create -f environment.yml
```
conda env create -f environment.yml
```

Activate the environment:

```bash
source activate jupyter_docs
source activate jupyter_docs
```

Build the docs:
**Build the docs** using Sphinx with the following commands:

```bash
make clean
make clean
make html
```

The docs will be built in `build/html`. They can be viewed by opening `build/html/index.html` or starting an HTTP server and navigating to `0.0.0.0:8000` in your web browser.

```bash
python3 -m http.server
```

## Releasing the jupyter metapackage

Anyone with push access to this repo can make a release
of the Jupyter metapackage (this happens very rarely).
We use [tbump][] to publish releases.

tbump updates version numbers and publishes the `git tag` of the version.
[Our GitHub Actions](https://github.com/jupyter/jupyter/actions)
then build the releases and publish them to PyPI.

The steps involved:

1. Install tbump: `pip install tbump`
2. Tag and publish the release `tbump $NEW_VERSION`.

That's it!

[tbump]: https://github.com/your-tools/tbump
123 changes: 123 additions & 0 deletions docs/.tx/config
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
[main-po--master]
host = https://www.transifex.com

[jupyter-meta-documentation.contrib_docs-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/contrib_docs.po
source_file = source/locale/en/LC_MESSAGES/contrib_docs.po
source_lang = en
type = PO

[jupyter-meta-documentation.releases-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/releases.po
source_file = source/locale/en/LC_MESSAGES/releases.po
source_lang = en
type = PO

[jupyter-meta-documentation.ipython-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/ipython.po
source_file = source/locale/en/LC_MESSAGES/ipython.po
source_lang = en
type = PO

[jupyter-meta-documentation.community-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/community.po
source_file = source/locale/en/LC_MESSAGES/community.po
source_lang = en
type = PO

[jupyter-meta-documentation.install-kernel-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/install-kernel.po
source_file = source/locale/en/LC_MESSAGES/install-kernel.po
source_lang = en
type = PO

[jupyter-meta-documentation.developer-docs-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/developer-docs.po
source_file = source/locale/en/LC_MESSAGES/developer-docs.po
source_lang = en
type = PO

[jupyter-meta-documentation.contributor-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/contributor.po
source_file = source/locale/en/LC_MESSAGES/contributor.po
source_lang = en
type = PO

[jupyter-meta-documentation.architecture-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/architecture.po
source_file = source/locale/en/LC_MESSAGES/architecture.po
source_lang = en
type = PO

[jupyter-meta-documentation.reference-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/reference.po
source_file = source/locale/en/LC_MESSAGES/reference.po
source_lang = en
type = PO

[jupyter-meta-documentation.install-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/install.po
source_file = source/locale/en/LC_MESSAGES/install.po
source_lang = en
type = PO

[jupyter-meta-documentation.projects-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/projects.po
source_file = source/locale/en/LC_MESSAGES/projects.po
source_lang = en
type = PO

[jupyter-meta-documentation.running-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/running.po
source_file = source/locale/en/LC_MESSAGES/running.po
source_lang = en
type = PO

[jupyter-meta-documentation.glossary-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/glossary.po
source_file = source/locale/en/LC_MESSAGES/glossary.po
source_lang = en
type = PO

[jupyter-meta-documentation.sphinx-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/sphinx.po
source_file = source/locale/en/LC_MESSAGES/sphinx.po
source_lang = en
type = PO

[jupyter-meta-documentation.content-quickstart-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/content-quickstart.po
source_file = source/locale/en/LC_MESSAGES/content-quickstart.po
source_lang = en
type = PO

[jupyter-meta-documentation.contents-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/contents.po
source_file = source/locale/en/LC_MESSAGES/contents.po
source_lang = en
type = PO

[jupyter-meta-documentation.tryjupyter-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/tryjupyter.po
source_file = source/locale/en/LC_MESSAGES/tryjupyter.po
source_lang = en
type = PO

[jupyter-meta-documentation.use-cases-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/use-cases.po
source_file = source/locale/en/LC_MESSAGES/use-cases.po
source_lang = en
type = PO

[jupyter-meta-documentation.development_guide-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/development_guide.po
source_file = source/locale/en/LC_MESSAGES/development_guide.po
source_lang = en
type = PO

[jupyter-meta-documentation.migrating-po--master]
file_filter = source/locale/<lang>/LC_MESSAGES/migrating.po
source_file = source/locale/en/LC_MESSAGES/migrating.po
source_lang = en
type = PO

7 changes: 7 additions & 0 deletions docs/doc-requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
sphinx>=3.1
sphinx-intl
myst_parser
nbsphinx
pydata-sphinx-theme
sphinxext-rediraffe
sphinx-panels
Loading

0 comments on commit 7404e45

Please sign in to comment.