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.

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

Tex format issue #98

Closed
wants to merge 24 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
ca2ee2b
lab7 checkin
phaustin Mar 21, 2020
4781a22
has bug
phaustin Mar 21, 2020
6276e90
to_push
phaustin Mar 21, 2020
e9794a7
pull_request
phaustin Mar 22, 2020
65b4bfb
pydata-sphinx namechange (#92)
phaustin Mar 21, 2020
af43ebb
bump version
chrisjsewell Mar 21, 2020
a72456f
DOCS: Remove extra pydata theme install (#93)
chrisjsewell Mar 21, 2020
b8ff5fc
updating glu to glue in directive+role (#91)
choldgraf Mar 24, 2020
6ac0277
udpating docs so bokeh and plotly show up (#100)
choldgraf Mar 25, 2020
0a65287
Add equation example to basic.ipynb example jupyter notebook (#102)
mtiley Mar 28, 2020
30e8fdf
FEAT: Jupyter-cache integration (#55)
AakashGfude Mar 28, 2020
7603ad4
bump release version (#103)
choldgraf Mar 28, 2020
e4dbe00
Add development documentation (#105)
chrisjsewell Mar 28, 2020
c398971
Fix cache outputs retrieval (#108)
chrisjsewell Mar 30, 2020
2173179
discard removed notebooks
chrisjsewell Mar 30, 2020
9982ead
Cache: get source suffixes from sphinx app, rather than hard-codind t…
chrisjsewell Mar 30, 2020
5296783
Adding singlehtml key to render priority (#111)
choldgraf Mar 31, 2020
1eb7372
DOC: Fixed typo in subsection heading (#113)
rossbar Mar 31, 2020
11edc56
DOC: Fixing CSS for math and small rearranging (#115)
choldgraf Mar 31, 2020
ed86afe
Documentation for unit testing (#112)
AakashGfude Mar 31, 2020
60a7360
Move to markdown-it-py markdown parser implementation (#107)
chrisjsewell Apr 1, 2020
e1ae89b
split files
phaustin Apr 1, 2020
9697463
add ghp-import
phaustin Apr 1, 2020
718f8d6
override gitignore
phaustin Apr 1, 2020
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 .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ coverage.xml
*.py,cover
.hypothesis/
.pytest_cache/
(PosixPath('/*

# Translations
*.mo
Expand Down Expand Up @@ -127,3 +128,6 @@ dmypy.json

# Pyre type checker
.pyre/

# Jupyter Cache
docs/.jupyter_cache
3 changes: 2 additions & 1 deletion .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ exclude: >
(?x)^(
\.vscode/settings\.json|
tests/commonmark/commonmark\.json|
.*\.xml
.*\.xml|
tests/.*\.txt
)$

repos:
Expand Down
1 change: 1 addition & 0 deletions .vscode/settings.json
Original file line number Diff line number Diff line change
Expand Up @@ -14,4 +14,5 @@
"python.linting.flake8Enabled": true,
"python.linting.enabled": true,
"python.pythonPath": "/anaconda/envs/ebp/bin/python",
"python.dataScience.useNotebookEditor": false
}
4 changes: 4 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -22,3 +22,7 @@ help:
# raise warnings to errors
html-strict:
@$(SPHINXBUILD) -b html -nW --keep-going "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)

# increase logging level to verbose
html-verbose:
@$(SPHINXBUILD) -b html -v "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
3 changes: 3 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -53,4 +53,7 @@
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["_static"]
jupyter_sphinx_require_url = ""

copybutton_selector = "div:not(.output) > div.highlight pre"

jupyter_execute_notebooks = "cache"
111 changes: 111 additions & 0 deletions docs/develop/contributing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
# Contributing

[![Travis-CI][travis-badge]][travis-link]
[![Coverage][coveralls-badge]][coveralls-link]
[![CircleCI][circleci-badge]][circleci-link]
[![Documentation Status][rtd-badge]][rtd-link]
[![Code style: black][black-badge]][black-link]

## Code Style

Code style is tested using [flake8](http://flake8.pycqa.org),
with the configuration set in `.flake8`,
and code formatted with [black](https://github.com/ambv/black).

Installing with `myst-parser[code_style]` makes the [pre-commit](https://pre-commit.com/)
package available, which will ensure this style is met before commits are submitted, by reformatting the code
and testing for lint errors.
It can be setup by:

```shell
>> cd MyST-NB
>> pre-commit install
```

Optionally you can run `black` and `flake8` separately:

```shell
>> black .
>> flake8 .
```

Editors like VS Code also have automatic code reformat utilities, which can adhere to this standard.

All functions and class methods should be annotated with types and include a docstring. The prefered docstring format is outlined in `MyST-NB/docstring.fmt.mustache` and can be used automatically with the
[autodocstring](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring) VS Code extension.

## Testing

For code tests:

```shell
>> cd MyST-NB
>> pytest
```

For documentation build tests:

```shell
>> cd MyST-NB/docs
>> make clean
>> make html-strict
```

## Pull Requests

To contribute, make Pull Requests to the `master` branch (this is the default branch). A PR can consist of one or multiple commits. Before you open a PR, make sure to clean up your commit history and create the commits that you think best divide up the total work as outlined above (use `git rebase` and `git commit --amend`). Ensure all commit messages clearly summarise the changes in the header and the problem that this commit is solving in the body.

Merging pull requests: There are three ways of 'merging' pull requests on GitHub:

- Squash and merge: take all commits, squash them into a single one and put it on top of the base branch.
Choose this for pull requests that address a single issue and are well represented by a single commit.
Make sure to clean the commit message (title & body)
- Rebase and merge: take all commits and 'recreate' them on top of the base branch. All commits will be recreated with new hashes.
Choose this for pull requests that require more than a single commit.
Examples: PRs that contain multiple commits with individually significant changes; PRs that have commits from different authors (squashing commits would remove attribution)
- Merge with merge commit: put all commits as they are on the base branch, with a merge commit on top
Choose for collaborative PRs with many commits. Here, the merge commit provides actual benefits.

[travis-link]: https://travis-ci.org/ExecutableBookProject/MyST-NB
[travis-badge]: https://travis-ci.org/ExecutableBookProject/MyST-NB.svg?branch=master
[coveralls-badge]: https://coveralls.io/repos/github/ExecutableBookProject/MyST-NB/badge.svg?branch=master
[coveralls-link]: https://coveralls.io/github/ExecutableBookProject/MyST-NB?branch=master
[circleci-badge]: https://circleci.com/gh/ExecutableBookProject/MyST-NB.svg?style=shield
[circleci-link]: https://circleci.com/gh/ExecutableBookProject/MyST-NB
[rtd-badge]: https://readthedocs.org/projects/myst-parser/badge/?version=latest
[rtd-link]: https://myst-parser.readthedocs.io/en/latest/?badge=latest
[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
[black-link]: https://github.com/ambv/black

## Unit Testing

Testing is one of the most important aspects of your PR. You should write test cases and verify your implementation by following the testing guide above. If you modify code related to existing unit tests, you must run appropriate commands and confirm that the tests still pass.

Note that we are using [pytest](https://docs.pytest.org/en/latest/) for testing, [pytest-regression](https://pytest-regressions.readthedocs.io/en/latest/) to self-generate/re-generate expected outcomes of test and [pytest-cov](https://pytest-cov.readthedocs.io/en/latest/) for checking coverage.

To run tests along with coverage:

```
pytest -v --cov=myst_nb
```

To run tests along with generation of an html coverage report:

```
pytest -v --cov=myst_nb --cov-report=html
```


### Test File and Directory Naming Conventions

Tests are found in the [tests](https://github.com/ExecutableBookProject/MyST-NB/tree/master/tests) directory. In order for `pytest` to find the test scripts correctly, the name of each test script should start with `test_` prefix.

### How to Write Tests

There are many examples of unit tests under the [tests](https://github.com/ExecutableBookProject/MyST-NB/tree/master/tests) directory, so reading some of them is a good and recommended way. Prefer using the `fixtures` and the classes defined in [conftest.py](https://github.com/ExecutableBookProject/MyST-NB/blob/master/tests/conftest.py) as much as possible.

If using [pytest-regression](https://pytest-regressions.readthedocs.io/en/latest/), a new directory with `test_` prefix is expected to be created in the first test run. This will store your expected output against which subsequent test outputs will be compared.

### Code Coverage report

[pytest-cov](https://pytest-cov.readthedocs.io/en/latest/) is used to generate code coverage report. Make sure that your test cases cover most of the code written by you. Expect the coverage build in Travis CI to fail if the overall coverage of the repository decreases.
8 changes: 8 additions & 0 deletions docs/develop/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Developing MyST-NB

This section covers documentation relevant to developing and maintaining the MyST-NB
codebase, and some guidelines for how you can contribute.

```{toctree}
contributing.md
```
11 changes: 11 additions & 0 deletions docs/examples/austin_issue/build_website.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
#!/bin/bash -v
#
# move the ipynb files into the doc_notebooks folder
#
mkdir -p _build
#
# build the website
#
sphinx-build -N -v -b html . _build


79 changes: 79 additions & 0 deletions docs/examples/austin_issue/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# -*- coding: utf-8 -*-
#
# -- Project information -----------------------------------------------------

project = "Numeric course"
copyright = "Numeric project"
author = "Numeric Project"

# The short X.Y version
version = ""
# The full version, including alpha/beta/rc tags
release = "0.1"


# -- General configuration ---------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
# extensions = [
# "nbsphinx",
# "sphinx.ext.mathjax",
# ]

extensions = [
"myst_nb",
"sphinx.ext.mathjax",
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
source_suffix = ['.rst', '.ipynb']
# source_suffix = ".rst"

# The master toctree document.
master_doc = "index"

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# 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

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path .
exclude_patterns = [
"*.md",
"_build",
"Thumbs.db",
".DS_Store",
"**.ipynb_checkpoints",
]

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = "sphinx"

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = "pydata_sphinx_theme"
html_style = None
html_static_path = ["_static"]



# -- Extension configuration -------------------------------------------------
nbsphinx_allow_errors = True
17 changes: 17 additions & 0 deletions docs/examples/austin_issue/environment.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
name: myst
channels:
- conda-forge
- defaults
dependencies:
- python=3.7.*
- jupyter
- jupytext
- sphinx
- pydata-sphinx-theme
- ghp-import
- pip
- pip:
- git+https://github.com/ExecutableBookProject/MyST-NB.git
- jupyter-cache[cli]


9 changes: 9 additions & 0 deletions docs/examples/austin_issue/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
Numerical Methods
-----------------

.. toctree::
:maxdepth: 1

Lab 8 dollar signs <lab8/lab8_dollar_delim.ipynb>

Lab 8 environ <lab8/lab8_env_delim.ipynb>
Loading