diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..086e9ca7c --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,21 @@ +--- +# Read the Docs configuration file for Sphinx projects + +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + + +build: + os: ubuntu-24.04 + tools: + python: "3.12" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: conf.py + + +python: + install: + - requirements: docs/requirements.txt diff --git a/conf.py b/conf.py index ce941a486..d23dea4ca 100644 --- a/conf.py +++ b/conf.py @@ -46,8 +46,8 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['sphinx_markdown_tables', 'sphinx.ext.intersphinx', - 'sphinx.ext.coverage', 'sphinx.ext.autodoc'] +extensions = ['sphinx_markdown_tables', 'myst_parser', + 'sphinx.ext.intersphinx', 'sphinx.ext.coverage', 'sphinx.ext.autodoc'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -58,25 +58,14 @@ # source_suffix = ['.rst', '.md'] # source_suffix = '.md' -source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'} - - -# from recommonmark.parser import CommonMarkParser - -# The suffix of source filenames. - -# source_suffix = ['.rst', '.md'] - -# parsers = { -# '.md': CommonMarkParser, -# } - -# from sphinxcontrib.pandoc_markdown import MarkdownParser +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} -source_suffix = ['.rst', '.md'] -# source_parsers = { -# '.md': MarkdownParser, -# } +myst_enable_extensions = [ + 'dollarmath', +] # The master toctree document. @@ -87,7 +76,7 @@ # General information about the project. project = u'Spirit' -copyright = u'2017, Gideon Mueller and contributors' +copyright = u'2024, Gideon Mueller and contributors' author = u'Gideon Mueller and contributors' # The version info for the project you're documenting, acts as replacement for @@ -104,12 +93,19 @@ # # 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 +language = 'en' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['.github', '_build', '../core/docs/python-api/spirit.rst', 'Thumbs.db', '.DS_Store'] +exclude_patterns = [ + '.venv', + '.github', + '_build', + '../core/docs/python-api/spirit.rst', + 'Thumbs.db', + '.DS_Store', +] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' @@ -212,7 +208,7 @@ # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} +intersphinx_mapping = {'python': ('https://docs.python.org/', None)} def run_apidoc(_): @@ -244,14 +240,33 @@ def run_apidoc(_): build_dir = os.path.join(source_dir, 'build') if not os.path.exists(build_dir): os.mkdir(build_dir) - subprocess.check_call(['cmake', '..', '-DSPIRIT_BUILD_FOR_CXX=OFF', '-DSPIRIT_SKIP_HTST=ON'], cwd=build_dir) + subprocess.check_call([ + 'cmake', + '..', + '-DSPIRIT_BUILD_FOR_CXX=OFF', + '-DSPIRIT_BUILD_TEST=ON', + '-DSPIRIT_SKIP_HTST=ON', + ], + cwd=build_dir + ) subprocess.check_call(['make'], cwd=build_dir) # See https://stackoverflow.com/a/30144019 env = os.environ.copy() - env["SPHINX_APIDOC_OPTIONS"] = 'members,special-members,private-members,undoc-members,show-inheritance' + env["SPHINX_APIDOC_OPTIONS"] = ','.join( + [ + 'members', + 'special-members', + 'private-members', + 'undoc-members', + 'show-inheritance', + ] + ) subprocess.check_call([cmd_path] + options, env=env) + if not os.path.exists(apidoc_dir): + os.mkdir(apidoc_dir) + ##################### with open(os.path.join(apidoc_dir, 'parameters.rst'), "w") as parameters_file: parameters_file.write("spirit.parameters\n==================================\n\n") @@ -266,21 +281,5 @@ def run_apidoc(_): with open(os.path.join(apidoc_dir, 'spirit.parameters.mmf.rst'), 'r') as generated_file: parameters_file.write(generated_file.read()) - print("xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx") - print("xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx") - testfile = os.path.join(apidoc_dir, 'spirit.log.rst') - with open(testfile, 'r') as f: - print(f.read()) - print("yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy") - print("yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy") - testfile = os.path.join(apidoc_dir, 'spirit.geometry.rst') - with open(testfile, 'r') as f: - print(f.read()) - print("zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz") - print("zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz") - - if not os.path.exists(apidoc_dir): - os.mkdir(apidoc_dir) - def setup(app): - app.connect('builder-inited', run_apidoc) \ No newline at end of file + app.connect('builder-inited', run_apidoc) diff --git a/docs/index.rst b/docs/index.rst index a36ba7b5d..4872a614e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,6 +19,7 @@ Spirit - Spin Simulation Framework Input file specification <../core/docs/Input> Definitions <../core/docs/Definitions> Additional features <../core/docs/Features> + Hamiltonian <../core/docs/Hamiltonian> .. toctree:: :maxdepth: 2 @@ -58,4 +59,4 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` -* :ref:`search` \ No newline at end of file +* :ref:`search` diff --git a/docs/requirements-local.txt b/docs/requirements-local.txt new file mode 100644 index 000000000..82133027c --- /dev/null +++ b/docs/requirements-local.txt @@ -0,0 +1,2 @@ +sphinx +sphinx_rtd_theme diff --git a/docs/requirements.txt b/docs/requirements.txt index a9d877d96..dffbafcc9 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,6 @@ pandoc sphinx-markdown-tables +myst-parser numpy cmake gcc7 \ No newline at end of file