diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml new file mode 100644 index 0000000..24247ce --- /dev/null +++ b/.github/workflows/sphinx.yml @@ -0,0 +1,170 @@ +# Deploy Sphinx. This could be shorter, but we also do some extra +# stuff. +# +# License: CC-0. This is the canonical location of this file, which +# you may want to link to anyway: +# https://github.com/coderefinery/sphinx-lesson-template/blob/main/.github/workflows/sphinx.yml +# https://raw.githubusercontent.com/coderefinery/sphinx-lesson-template/main/.github/workflows/sphinx.yml + + +name: sphinx +on: [push, pull_request] + +env: + DEFAULT_BRANCH: "main" + # If these SPHINXOPTS are enabled, then be strict about the + # builds and fail on any warnings. + #SPHINXOPTS: "-W --keep-going -T" + GENERATE_PDF: true # to enable, must be 'true' lowercase + GENERATE_SINGLEHTML: true # to enable, must be 'true' lowercase + PDF_FILENAME: lesson.pdf + MULTIBRANCH: true # to enable, must be 'true' lowercase + + +jobs: + build: + name: Build + runs-on: ubuntu-latest + permissions: + contents: read + + steps: + # https://github.com/marketplace/actions/checkout + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + lfs: true + + # https://github.com/marketplace/actions/setup-python + # ^-- This gives info on matrix testing. + - name: Install Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + cache: 'pip' + + # https://docs.github.com/en/actions/guides/building-and-testing-python#installing-dependencies + # ^-- This gives info on installing dependencies with pip + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements.txt + + # Debug + - name: Debugging information + env: + ref: ${{github.ref}} + event_name: ${{github.event_name}} + head_ref: ${{github.head_ref}} + base_ref: ${{github.base_ref}} + run: | + echo "github.ref: ${ref}" + echo "github.event_name: ${event_name}" + echo "github.head_ref: ${head_ref}" + echo "github.base_ref: ${base_ref}" + echo "GENERATE_PDF: ${GENERATE_PDF}" + echo "GENERATE_SINGLEHTML: ${GENERATE_SINGLEHTML}" + set -x + git rev-parse --abbrev-ref HEAD + git branch + git branch -a + git remote -v + python -V + pip list --not-required + pip list + + + # Build + - uses: ammaraskar/sphinx-problem-matcher@master + - name: Build Sphinx docs (dirhtml) + # SPHINXOPTS used via environment variables + run: | + make dirhtml + # This fixes broken copy button icons, as explained in + # https://github.com/coderefinery/sphinx-lesson/issues/50 + # https://github.com/executablebooks/sphinx-copybutton/issues/110 + # This can be removed once these PRs are accepted (but the + # fixes also need to propagate to other themes): + # https://github.com/sphinx-doc/sphinx/pull/8524 + # https://github.com/readthedocs/sphinx_rtd_theme/pull/1025 + sed -i 's/url_root="#"/url_root=""/' _build/dirhtml/index.html || true + + # singlehtml + - name: Generate singlehtml + if: ${{ env.GENERATE_SINGLEHTML == 'true' }} + run: | + make singlehtml + mv _build/singlehtml/ _build/dirhtml/singlehtml/ + + # PDF if requested + - name: Generate PDF + if: ${{ env.GENERATE_PDF == 'true' }} + run: | + pip install https://github.com/rkdarst/sphinx_pyppeteer_builder/archive/refs/heads/main.zip + make pyppeteer + mv _build/pyppeteer/*.pdf _build/dirhtml/${PDF_FILENAME} + + # Stage all deployed assets in _gh-pages/ for simplicity, and to + # prepare to do a multi-branch deployment. + - name: Copy deployment data to _gh-pages/ + if: ${{ github.event_name == 'push' }} + run: + rsync -a _build/dirhtml/ _gh-pages/ + + # Use gh-pages-multibranch to multiplex different branches into + # one deployment. See + # https://github.com/coderefinery/gh-pages-multibranch + - name: gh-pages multibranch + uses: coderefinery/gh-pages-multibranch@main + if: ${{ github.event_name == 'push' && env.MULTIBRANCH == 'true' }} + with: + directory: _gh-pages/ + default_branch: ${{ env.DEFAULT_BRANCH }} + publish_branch: gh-pages + + # Add the .nojekyll file + - name: nojekyll + if: ${{ github.event_name == 'push' }} + run: | + touch _gh-pages/.nojekyll + + # Save artifact for the next step. + - uses: actions/upload-artifact@v4 + if: ${{ github.event_name == 'push' }} + with: + name: gh-pages-build + path: _gh-pages/ + + # Deploy in a separate job so that write permissions are restricted + # to the minimum steps. + deploy: + name: Deploy + runs-on: ubuntu-latest + needs: build + # This if can't use the env context - find better way later. + if: ${{ github.event_name == 'push' }} + permissions: + contents: write + + steps: + - uses: actions/download-artifact@v4 + if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }} + with: + name: gh-pages-build + path: _gh-pages/ + + # As of 2023, we could publish to pages via a Deployment. This + # isn't done yet to give it time to stabilize (out of beta), and + # also having a gh-pages branch to check out is rather + # convenient. + + # Deploy + # https://github.com/peaceiris/actions-gh-pages + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }} + with: + publish_branch: gh-pages + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: _gh-pages/ + force_orphan: true diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c0d3369 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +/_build +.ipynb_checkpoints +/venv* +.jupyter_cache +jupyter_execute diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..46f35b9 --- /dev/null +++ b/Makefile @@ -0,0 +1,24 @@ +# 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 = content +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) + +# Live reload site documents for local development +livehtml: + sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/content/01_Introduction/Introduction.md b/content/01_Introduction/Introduction.md new file mode 100644 index 0000000..ce10634 --- /dev/null +++ b/content/01_Introduction/Introduction.md @@ -0,0 +1 @@ +## Введение \ No newline at end of file diff --git a/content/Figures/ysda_logo.png b/content/Figures/ysda_logo.png new file mode 100644 index 0000000..56c75e7 Binary files /dev/null and b/content/Figures/ysda_logo.png differ diff --git a/content/Figures/ysda_logo_upscaled.png b/content/Figures/ysda_logo_upscaled.png new file mode 100644 index 0000000..e324d83 Binary files /dev/null and b/content/Figures/ysda_logo_upscaled.png differ diff --git a/content/conf.py b/content/conf.py new file mode 100644 index 0000000..719e3da --- /dev/null +++ b/content/conf.py @@ -0,0 +1,109 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = "YSDA Course" +copyright = "2024" +author = "Authors" +github_user = "yandexdataschool" +github_repo_name = "" # auto-detected from dirname if blank +github_version = "main" +conf_py_path = "/content/" # with leading and trailing slash + +# -- 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 = [ + # githubpages just adds a .nojekyll file + "sphinx.ext.githubpages", + "sphinx_lesson", + # remove once sphinx_rtd_theme updated for contrast and accessibility: + "sphinx_rtd_theme_ext_color_contrast", +] + +myst_enable_extensions = [ + "colon_fence", # ::: can be used instead of ``` for better rendering + ] + +# Settings for myst_nb: +# https://myst-nb.readthedocs.io/en/latest/computation/execute.html#notebook-execution-modes +# nb_execution_mode = "off" +# nb_execution_mode = "auto" # *only* execute if at least one output is missing. +# nb_execution_mode = "force" +# nb_execution_mode = "cache" +nb_execution_mode = "cache" + +# 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 = [ + "README*", + "_build", + "Thumbs.db", + ".DS_Store", + "jupyter_execute", + "*venv*", +] + + +# -- 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_rtd_theme" +html_logo = "Figures/ysda_logo_upscaled.png" + +# 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 context: +from os.path import basename, dirname, realpath + +html_context = { + "display_github": True, + "github_user": github_user, + # Auto-detect directory name. This can break, but + # useful as a default. + "github_repo": github_repo_name or basename(dirname(realpath(__file__))), + "github_version": github_version, + "conf_py_path": conf_py_path, +} + +# Intersphinx mapping. For example, with this you can use +# :py:mod:`multiprocessing` to link straight to the Python docs of that module. +# List all available references: +# python -msphinx.ext.intersphinx https://docs.python.org/3/objects.inv +# extensions.append('sphinx.ext.intersphinx') +# intersphinx_mapping = { +# #'python': ('https://docs.python.org/3', None), +# #'sphinx': ('https://www.sphinx-doc.org/', None), +# #'numpy': ('https://numpy.org/doc/stable/', None), +# #'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None), +# #'pandas': ('https://pandas.pydata.org/docs/', None), +# #'matplotlib': ('https://matplotlib.org/', None), +# 'seaborn': ('https://seaborn.pydata.org/', None), +# } diff --git a/content/index.md b/content/index.md new file mode 100644 index 0000000..21efeeb --- /dev/null +++ b/content/index.md @@ -0,0 +1,16 @@ +# Название курса + +## Краткое описание + +## Программа + +## Критерии оценивания + +## Полезные ссылки + +```{toctree} +:maxdepth: 1 +:caption: Лекции + +01_Introduction/Introduction +``` diff --git a/make.bat b/make.bat new file mode 100644 index 0000000..6bd7cd2 --- /dev/null +++ b/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=content +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/requirements.txt b/requirements.txt new file mode 100644 index 0000000..135f7aa --- /dev/null +++ b/requirements.txt @@ -0,0 +1,5 @@ +Sphinx +sphinx_rtd_theme +sphinx_rtd_theme_ext_color_contrast +myst_nb +sphinx-lesson