Skip to content

Commit 5818eea

Browse files
AakashGfudemmcky
AakashGfude
and
mmcky
authored
📚 DOCS: docs update (#37)
* docs update * edits for docs * building pdf in ci * doc requires * checking out a branch * ci cloning jupyter-book branch * install xindy * testing workflows * adding pdf doc build * shuffling pdf build workflow * shuffling pdf build * added a new workflow file for pdf * formatting * change till jupyterbok-latex is introduced in the docs * path of artifact Co-authored-by: mmcky <[email protected]>
1 parent 4c7ccff commit 5818eea

File tree

5 files changed

+87
-39
lines changed

5 files changed

+87
-39
lines changed

‎.github/workflows/ci.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ jobs:
4444
texlive-xetex \
4545
texlive-latex-extra \
4646
texlive-fonts-extra \
47+
xindy \
4748
latexmk
4849
4950
- name: Run pytest

‎.github/workflows/pdf.yml

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
name: Build PDF of Jupyterbook Docs
2+
3+
on:
4+
push:
5+
branches: [master]
6+
tags:
7+
- 'v*'
8+
pull_request:
9+
10+
jobs:
11+
12+
pdflatex:
13+
14+
runs-on: ubuntu-latest
15+
strategy:
16+
matrix:
17+
python-version: [3.8]
18+
19+
steps:
20+
- uses: actions/checkout@v2
21+
- name: Set up Python ${{ matrix.python-version }}
22+
uses: actions/setup-python@v2
23+
with:
24+
python-version: ${{ matrix.python-version }}
25+
- name: Install Python dependencies
26+
run: |
27+
python -m pip install --upgrade pip
28+
pip install wheel
29+
pip install -e .[testing]
30+
- name: Install latex dependencies
31+
run: |
32+
sudo apt-get -qq update
33+
sudo apt-get install -y \
34+
texlive-latex-recommended \
35+
texlive-latex-extra \
36+
texlive-fonts-recommended \
37+
texlive-fonts-extra \
38+
texlive-xetex \
39+
latexmk \
40+
xindy
41+
42+
- name: Build PDF from LaTeX (Docs)
43+
run: |
44+
git clone -b latex-tocd https://github.com/AakashGfude/jupyter-book.git
45+
cd jupyter-book
46+
pip install -e .[sphinx]
47+
jb build docs --builder pdflatex -n -W --keep-going
48+
- uses: actions/upload-artifact@v2
49+
with:
50+
name: PDF_LATEX
51+
path: jupyter-book/docs/_build/latex/book.pdf

‎docs/_config.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Book settings
22
# Learn more at https://jupyterbook.org/customize/config.html
33

4-
title: Jupyterbook-latex docs
4+
title: jupyterbook-latex docs
55
author: The Jupyter Book Community
66

77
# Force re-execution of notebooks on each build.

‎docs/contributing.md

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,23 +27,26 @@ pip install -e .[code_style,testing]
2727

2828
### Unit Testing
2929

30-
We use pytest for testing, pytest-regression to regenerate expected outcomes of test and pytest-cov for checking coverage.
30+
We use `pytest` for testing, `pytest-regression` to regenerate expected outcomes of test,
31+
and `pytest-cov` for checking coverage.
3132

32-
To simply run existing tests:
33+
To run all tests:
3334

3435
```bash
3536
pytest
3637
```
3738

38-
To run tests with coverage and an html coverage report:
39+
To run tests with `coverage` and an html coverage report:
3940

4041
```bash
4142
pytest --cov=jupyterbook_latex --cov-report=html
4243
```
4344

4445
### Coding Style
4546

46-
The consistency and code style in this project is enforced with multiple automated pre-commit hooks. You can install(recommend) and run them using:
47+
The consistency and code style in this project is enforced with multiple automated pre-commit hooks.
48+
49+
To set up please run:
4750

4851
```bash
4952
pre-commit install

‎docs/intro.md

Lines changed: 27 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,21 @@
11
# jupyterbook-latex
22

3-
**An extension to handle latex side of things for jupyter-book**.
3+
**Improvements to LaTeX for jupyter-book**.
44

55
This package contains a [Sphinx](http://www.sphinx-doc.org/en/master/)
66
extension to handle LaTeX builds for [jupyter-book](https://jupyterbook.org/)
77
projects and to implement features specific to LaTeX.
88

9-
```{warning}
10-
jupyterbook-latex is in an active development stage and may change rapidly.
11-
```
12-
139
(getting-started)=
1410
## Getting Started
1511

16-
To get started with `jupyterbook-latex`, first clone the Github [repo](https://github.com/executablebooks/jupyterbook-latex) locally:
17-
18-
```bash
19-
git clone https://github.com/executablebooks/jupyterbook-latex
20-
```
21-
22-
and then install using the setup file
12+
To get started with `jupyterbook-latex`, first install it through pip:
2313

2414
```bash
25-
cd jupyterbook-latex
26-
python setup.py install
15+
pip install jupyterbook-latex
2716
```
2817

29-
### Configuration
30-
31-
Add this extension to the extensions list in your sphinx project's `conf.py`:
18+
Then add this extension to the extensions list in your sphinx project's `conf.py`:
3219

3320
```python
3421
extensions = ["jupyterbook_latex"]
@@ -41,51 +28,57 @@ A list of features that are implemented in this `jupyter-book` extension:
4128

4229
### Table Of Contents Page:
4330

44-
* `part` key in `_toc.yml` is handled in the pdf output.
45-
With the part name specified in `_toc.yml` being the part
46-
name in the output.
31+
* Support for [parts/chapter structure](https://jupyterbook.org/customize/toc.html#defining-chapters-and-parts-in-toc-yml) in `_toc.yml` is implemented and
32+
will preserve the intended document structure when producing the `latex`/`pdf`.
4733

4834
* Files specified under `chapters:` in `_toc.yml` are translated
4935
to chapters in pdf output.
5036

5137
* Files specified under the `sections:` key are included
52-
in the parent `chapter` document with file title being `h2` headers in the document.
38+
in the parent `chapter` document with file title being `h2`
39+
headers in the document.
5340

54-
* Master document is not included in table of contents page
55-
and is instead treated as a frontmatter.
41+
* The `master document` is not included in table of contents page
42+
and is instead treated as a `frontmatter`.
5643

5744
* `url` key in `_toc.yml` is being ignored in the final
58-
pdf output. [`tableofcontents`](https://jupyterbook.org/customize/toc.html#add-a-table-of-contents-to-a-page-s-content) directive is
59-
also ignored at present, but plans to handle it in a later
60-
release is underway.
45+
pdf output.
46+
47+
* Support for `tableofcontents`](https://jupyterbook.org/customize/toc.html#add-a-table-of-contents-to-a-page-s-content) directives in `LaTeX`
48+
is translated as a list with links preserved.
6149

6250
* The table of contents page title is fixed to be `Contents` at present.
6351

6452
### Master Document:
6553

66-
Master doc page is treated as a front matter page. Like an `Introduction` to the book and does not appear in Table Of Contents. All the sections and sub-sections in the Master doc are internally converted to bolded text of varying sizes based on the level of the section.
54+
The `masterdoc` page is treated strictly as `front matter`. This is similar to an `Introduction` to the book and does not appear in Table Of Contents. All the sections and sub-sections in the `masterdoc` are internally converted to bolded text of varying sizes based on the level of the section.
6755

6856
### Code Cell Tags:
6957

7058
A list of available tags can be found in https://jupyterbook.org/reference/cheatsheet.html#tags
7159

72-
* `hide-cell` is handled by removing the input and output cell content in the pdf output.
60+
* `hide-cell` is handled by removing the input and output cell content in the `pdf` output.
7361

74-
* `hide-input` is handled by removing the cell but displaying the output in the pdf output.
62+
* `hide-input` is handled by removing the cell but displaying the output in the `pdf` output.
7563

76-
* `hide-output` is handled by removing the outputs of a cell in the pdf output.
64+
* `hide-output` is handled by removing the outputs of a cell in the `pdf` output.
7765

7866
### Others:
7967

8068
* Handling of `png` and `gif` images using `sphinx.ext.imgconverter` package.
81-
Which uses [ImageMagick](https://www.imagemagick.org/script/index.php), so
82-
make sure to have it installed in your system.
69+
Which uses [ImageMagick](https://www.imagemagick.org/script/index.php), which
70+
will need to be installed on your system to work.
71+
72+
```{note}
73+
[ImageMagick](https://www.imagemagick.org/script/index.php) is not installed by default
74+
so it is up to users to provide this software
75+
```
8376

8477
* Fonts used at the moment are [GNU Free Fonts](https://www.gnu.org/software/freefont/),
8578
but it may change in the near future owing to its handling of math characters.
8679

8780
* Direct LaTeX syntax for math is handled by default in source documents
8881
using `myst_amsmath_enable` key of `jupyter-book`.
89-
More info in [https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html#syntax-amsmath](https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html#syntax-amsmath)
82+
More info on [myst_amsmath_enable](https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html#syntax-amsmath).
9083

91-
* `xelatex` is used as the default LaTeX engine because of its support for unicode characters.
84+
* `xelatex` is used as the **default LaTeX engine** because of its support for unicode characters.

0 commit comments

Comments
 (0)