From cf03c817e268ca78b3470a978661f7993125bfc9 Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Mon, 13 Jan 2025 17:28:44 -0800 Subject: [PATCH] Sphinx Me Up --- .gitignore | 3 ++ .readthedocs.yaml | 2 +- Makefile | 20 +++++++++ conda.yml | 2 + front_matter/how_to_write_docs.md | 42 ------------------- make.bat | 35 ++++++++++++++++ myst.yml | 12 +++--- source/conf.py | 28 +++++++++++++ .../front_matter}/contributing.md | 2 +- .../front_matter}/governance.md | 0 source/front_matter/how_to_write_docs.md | 40 ++++++++++++++++++ .../front_matter}/introduction.md | 0 source/index.md | 21 ++++++++++ .../standard}/element_parameter.md | 0 {standard => source/standard}/introduction.md | 0 15 files changed, 157 insertions(+), 50 deletions(-) create mode 100644 Makefile delete mode 100644 front_matter/how_to_write_docs.md create mode 100644 make.bat create mode 100644 source/conf.py rename {front_matter => source/front_matter}/contributing.md (91%) rename {front_matter => source/front_matter}/governance.md (100%) create mode 100644 source/front_matter/how_to_write_docs.md rename {front_matter => source/front_matter}/introduction.md (100%) create mode 100644 source/index.md rename {standard => source/standard}/element_parameter.md (100%) rename {standard => source/standard}/introduction.md (100%) diff --git a/.gitignore b/.gitignore index eac0968..5899e1c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,5 @@ +# Sphinx outputs +build + # MyST build outputs _build diff --git a/.readthedocs.yaml b/.readthedocs.yaml index aa0d61e..87e1f9d 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -11,7 +11,7 @@ build: python: "mambaforge-latest" sphinx: - configuration: conf.py + configuration: source/conf.py conda: environment: conda.yml diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/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/conda.yml b/conda.yml index 00f213a..97a1276 100644 --- a/conda.yml +++ b/conda.yml @@ -17,6 +17,8 @@ dependencies: - pygments - recommonmark - sphinx + - sphinx-autobuild + - sphinx-book-theme - sphinx-copybutton - sphinx-design - sphinxcontrib-bibtex diff --git a/front_matter/how_to_write_docs.md b/front_matter/how_to_write_docs.md deleted file mode 100644 index bfe3c40..0000000 --- a/front_matter/how_to_write_docs.md +++ /dev/null @@ -1,42 +0,0 @@ -# How to Write Documentation - -The documentation uses the [MyST](https://mystmd.org/) markup language. - -In order to edit and view the documentation locally, please first install MyST following [MyST's installation instructions](https://mystmd.org/guide/installing). - -Check that MyST has been installed successfully by running -```{code} bash -myst --version -``` -Once MyST has been installed, run -```{code} bash -myst start -``` -from the root directory of the repository (where the MyST configuration file `myst.yml` is located) to start MyST locally. -This will display something like -```{code} bash -$ myst start - -📖 Built front_matter/introduction.md in 96 ms. -📖 Built front_matter/governance.md in 46 ms. -📖 Built front_matter/contributing.md in 45 ms. -📖 Built front_matter/doc_editing_setup.md in 45 ms. -📖 Built standard/introduction.md in 45 ms. -📖 Built standard/element_parameter.md in 44 ms. -📚 Built 6 pages for project in 193 ms. - - ✨✨✨ Starting Book Theme ✨✨✨ - -🔌 Server started on port 3000! 🥳 🎉 - - 👉 http://localhost:3000 👈 -``` - -Open the URL displayed in the terminal (in this case `http://localhost:3000`) to visualize the MyST content with your web browser. - -You are now ready to edit the markdown files that compose the documentation! -The content displayed in your web browser will update automatically as you edit. - -If you add new markdown files, do not forget to add them to the table of contents defined in the MyST configuration file `myst.yml`. - -Finally, once you are happy with your changes, do not forget to commit and push them to your branch and open a pull request on GitHub. diff --git a/make.bat b/make.bat new file mode 100644 index 0000000..747ffb7 --- /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=source +set BUILDDIR=build + +%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.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/myst.yml b/myst.yml index babfa3d..b7daf1a 100644 --- a/myst.yml +++ b/myst.yml @@ -8,16 +8,16 @@ project: # authors: [] github: https://github.com/campa-consortium/lattice-standard toc: - - file: 'front_matter/introduction.md' + - file: 'source/front_matter/introduction.md' - title: 'Front Matter' children: - - file: 'front_matter/governance.md' - - file: 'front_matter/contributing.md' - - file: 'front_matter/how_to_write_docs.md' + - file: 'source/front_matter/governance.md' + - file: 'source/front_matter/contributing.md' + - file: 'source/front_matter/how_to_write_docs.md' - title: 'Lattice Standard' children: - - file: 'standard/introduction.md' - - file: 'standard/element_parameter.md' + - file: 'source/standard/introduction.md' + - file: 'source/standard/element_parameter.md' site: template: book-theme #domains: diff --git a/source/conf.py b/source/conf.py new file mode 100644 index 0000000..d3927e2 --- /dev/null +++ b/source/conf.py @@ -0,0 +1,28 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Accelerator Lattice Standard' +copyright = '2025, under CC-BY 4.0 License' +author = 'Jean-Luc Vay, David Sagan, Chad Mitchell, Axel Huebl, David Bruhwihler, Christopher Mayes, Eric Stern, Daniel Winklehner, Michael Ehrlichman, Martin Berz, Giovanni Iadarola, Ji Qiang, Edoardo Zoni, Laurent Deniau, et al.' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ['myst_parser', 'sphinx_design'] +myst_enable_extensions = ["colon_fence"] + +templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_book_theme' +html_static_path = ['_static'] diff --git a/front_matter/contributing.md b/source/front_matter/contributing.md similarity index 91% rename from front_matter/contributing.md rename to source/front_matter/contributing.md index 7e40e2e..792c6d0 100644 --- a/front_matter/contributing.md +++ b/source/front_matter/contributing.md @@ -62,6 +62,6 @@ git commit -m "Add element template." git push -u username add_template ``` -8. Follow the link that is generated to open a new pull request on GitHub that includes these changes, e.g., go to https://github.com/cemitch99/lattice-standard/pull/new/add_template. +8. Follow the link that is generated to open a new pull request on GitHub that includes these changes, e.g., go to [https://github.com/cemitch99/lattice-standard/pull/new/add_template](https://github.com/cemitch99/lattice-standard/pull/new/add_template). 9. Add a title and additional information relevant to the pull request (as needed). diff --git a/front_matter/governance.md b/source/front_matter/governance.md similarity index 100% rename from front_matter/governance.md rename to source/front_matter/governance.md diff --git a/source/front_matter/how_to_write_docs.md b/source/front_matter/how_to_write_docs.md new file mode 100644 index 0000000..0dc6e61 --- /dev/null +++ b/source/front_matter/how_to_write_docs.md @@ -0,0 +1,40 @@ +# How to Write Documentation + +The documentation uses the [MyST](https://mystmd.org/) markup language and renders to [Sphinx](https://www.sphinx-doc.org) as HTML, PDF or EPUB documents. + +In order to build the documentation locally, please create a software environment like this + +```{code} bash +conda env create -y -f conda.yml +conda activate lattice-standard +``` + +and compile via + +::::{tab-set} + +:::{tab-item} HTML +```{code} bash +make html +``` +::: + +:::{tab-item} PDF +```{code} bash +make latexpdf +``` +::: + +:::: + +Open the file `build/html/index.html` with your web browser to visualize. +You are now ready to edit the markdown files that compose the documentation! + +If you like to atuomatically rebuild changes on save of edited files, run: +```{code} bash +sphinx-autobuild source/ build/html +``` +and open the URL shown in the terminal, usually [http://127.0.0.1:8000](http://127.0.0.1:8000). + +If you add new markdown files, do not forget to add them to the table of contents defined `source/index.md`. +Finally, once you are happy with your changes, do not forget to commit and push them to your branch and open a pull request on GitHub. diff --git a/front_matter/introduction.md b/source/front_matter/introduction.md similarity index 100% rename from front_matter/introduction.md rename to source/front_matter/introduction.md diff --git a/source/index.md b/source/index.md new file mode 100644 index 0000000..da93901 --- /dev/null +++ b/source/index.md @@ -0,0 +1,21 @@ +# Accelerator Lattice Standard + +This standard is an effort to create a standard to promote lattice information exchange for particle accelerators. + +```{toctree} +:maxdepth: 1 +:caption: Front Matter + +front_matter/introduction.md +front_matter/governance.md +front_matter/contributing.md +front_matter/how_to_write_docs.md +``` + +```{toctree} +:maxdepth: 1 +:caption: Standard + +standard/introduction.md +standard/element_parameter.md +``` diff --git a/standard/element_parameter.md b/source/standard/element_parameter.md similarity index 100% rename from standard/element_parameter.md rename to source/standard/element_parameter.md diff --git a/standard/introduction.md b/source/standard/introduction.md similarity index 100% rename from standard/introduction.md rename to source/standard/introduction.md