👌 IMPROVE: Changes for readthedocs (#50)

AakashGfude · web-flow · commit d29a6364642e · 2021-03-15T17:00:02.000+11:00
* reformatted docs page

* added things in gitignore

* removing latex-tocd branch cloning

* fixing version of bibtes

* changed the cloning directory to executablebooks
diff --git a/.github/workflows/pdf.yml b/.github/workflows/pdf.yml
@@ -41,7 +41,7 @@ jobs:
 
     - name: Build PDF from LaTeX (Docs)
       run: |
-        git clone -b latex-tocd https://github.com/AakashGfude/jupyter-book.git
+        git clone https://github.com/executablebooks/jupyter-book.git
         cd jupyter-book
         pip install -e .[sphinx]
         jb build docs --builder pdflatex -n -W --keep-going
diff --git a/.gitignore b/.gitignore
@@ -5,6 +5,8 @@ build/
 dist/
 *.egg-info/
 _build/
+_static
+_templates
 .DS_Store
 
 
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,18 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  version: 3.7
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - rtd
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_config.yml b/docs/_config.yml
diff --git a/docs/_toc.yml b/docs/_toc.yml
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,49 @@
+# Configuration file for the Sphinx documentation builder.
+import os
+
+# -- Project information -----------------------------------------------------
+project = "Jupyterbook-latex"
+copyright = "2020, Executable Book Project"
+author = "Executable Book Project"
+master_doc = "intro"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
+# ones.
+extensions = ["jupyterbook_latex", "myst_parser"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# 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 = ["_build"]
+
+html_static_path = ["_static"]
+
+# -- 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 = "sphinx_book_theme"
+
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ["_static"]
+
+html_theme_options = {
+    "path_to_docs": "docs/",
+    "repository_url": "https://github.com/executablebooks/jupyterbook-latex",
+    "use_edit_page_button": True,
+}
+
+jupyter_execute_notebooks = "cache"
+execution_show_tb = "READTHEDOCS" in os.environ
+execution_timeout = 60  # Note: 30 was timing out on RTD
diff --git a/docs/source/contributing.md b/docs/source/contributing.md
diff --git a/docs/source/intro.md b/docs/source/intro.md
@@ -1,11 +1,20 @@
-# jupyterbook-latex
+# Jupyterbook-latex
 
 **Improvements to LaTeX for jupyter-book**.
 
 This package contains a [Sphinx](http://www.sphinx-doc.org/en/master/)
 extension to handle LaTeX builds for [jupyter-book](https://jupyterbook.org/)
 projects and to implement features specific to LaTeX.
 
+## Site Contents
+
+```{toctree}
+---
+maxdepth: 1
+---
+contributing.md
+```
+
 (getting-started)=
 ## Getting Started
 
@@ -22,7 +31,7 @@ extensions = ["jupyterbook_latex"]
 ```
 
 (feature-list)=
-## Feature List
+## Features List
 
 A list of features that are implemented in this `jupyter-book` extension:
 
@@ -35,27 +44,27 @@ A list of features that are implemented in this `jupyter-book` extension:
   to chapters in pdf output.
 
 * Files specified under the `sections:` key are included
-  in the parent `chapter` document with file title being `h2`
-  headers in the document.
+  in the parent `chapter` document, with the file title being the `h2`
+  header in the document.
 
 * The `master document` is not included in table of contents page
   and is instead treated as a `frontmatter`.
 
 * `url` key in `_toc.yml` is being ignored in the final
   pdf output.
 
-* Support for `tableofcontents`](https://jupyterbook.org/customize/toc.html#add-a-table-of-contents-to-a-page-s-content) directives in `LaTeX`
-  is translated as a list with links preserved.
+* [`tableofcontents`](https://jupyterbook.org/customize/toc.html#add-a-table-of-contents-to-a-page-s-content) directive
+  is translated as a list, with the links preserved.
 
-* The table of contents page title is fixed to be `Contents` at present.
+* The `Table Of Contents` page title is fixed, with the value being "Contents".
 
 ### Master Document:
 
 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.
 
 ### Code Cell Tags:
 
-A list of available tags can be found in https://jupyterbook.org/reference/cheatsheet.html#tags
+A list of available tags can be found in [https://jupyterbook.org/reference/cheatsheet.html#tags]
 
 * `hide-cell` is handled by removing the input and output cell content in the `pdf` output.
 
@@ -67,18 +76,18 @@ A list of available tags can be found in https://jupyterbook.org/reference/cheat
 
 * Handling of `png` and `gif` images using `sphinx.ext.imgconverter` package.
   Which uses [ImageMagick](https://www.imagemagick.org/script/index.php), which
-  will need to be installed on your system to work.
+  needs to be installed on your system to work.
 
 ```{note}
 [ImageMagick](https://www.imagemagick.org/script/index.php) is not installed by default
-so it is up to users to provide this software
+so it is up to the users to install this software.
 ```
 
 * Fonts used at the moment are [GNU Free Fonts](https://www.gnu.org/software/freefont/),
   but it may change in the near future owing to its handling of math characters.
 
 * Direct LaTeX syntax for math is handled by default in source documents
   using `myst_amsmath_enable` key of `jupyter-book`.
-  More info on [myst_amsmath_enable](https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html#syntax-amsmath).
+  More info on [this](https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html#syntax-amsmath) page.
 
 * `xelatex` is used as the **default LaTeX engine** because of its support for unicode characters.
diff --git a/setup.py b/setup.py
@@ -34,7 +34,7 @@
             "pytest-regressions",
             "texsoup",
             "jupyter-book",
-            "sphinxcontrib-bibtex",
+            "sphinxcontrib-bibtex~=2.1.0",
         ],
         "rtd": [
             "sphinx>=3.0",
