diff --git a/ci/doc.yml b/ci/doc.yml index 5a3afbdf..fc9baeb0 100644 --- a/ci/doc.yml +++ b/ci/doc.yml @@ -6,14 +6,18 @@ dependencies: - python>=3.8 - netcdf4 - scipy - - sphinx + - sphinx>=4.2.0 - sphinx-copybutton - - numpydoc + - sphinx-panels - sphinx-autosummary-accessors + - sphinx-book-theme >= 0.0.38 + - pydata-sphinx-theme>=0.4.3 + - numpydoc - ipython - h5netcdf - zarr - pip: - git+https://github.com/xarray-contrib/datatree - - pangeo-sphinx-book-theme + - sphinxext-rediraffe + - sphinxext-opengraph - xarray>=2022.05.0.dev0 diff --git a/docs/Makefile b/docs/Makefile index 9b5b6042..6e9b4058 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -19,11 +19,12 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) sou # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext +.PHONY: help clean html rtdhtml dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" + @echo " rtdhtml Build html using same settings used on ReadtheDocs" @echo " dirhtml to make HTML files named index.html in directories" @echo " singlehtml to make a single large HTML file" @echo " pickle to make pickle files" @@ -54,6 +55,11 @@ html: @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." +rtdhtml: + $(SPHINXBUILD) -T -j auto -E -W --keep-going -b html -d $(BUILDDIR)/doctrees -D language=en . $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo diff --git a/docs/source/conf.py b/docs/source/conf.py index d330c920..e95bc2bc 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -45,6 +45,9 @@ "sphinx.ext.intersphinx", "sphinx.ext.extlinks", "sphinx.ext.napoleon", + "sphinx_copybutton", + "sphinxext.opengraph", + "sphinx_autosummary_accessors", "IPython.sphinxext.ipython_console_highlighting", "IPython.sphinxext.ipython_directive", ] @@ -131,7 +134,11 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "pangeo_sphinx_book_theme" +html_theme = "sphinx_book_theme" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. html_theme_options = { "repository_url": "https://github.com/xarray-contrib/datatree", "repository_branch": "main", @@ -141,11 +148,6 @@ "use_edit_page_button": True, } -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# html_theme_options = {} - # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] @@ -168,7 +170,7 @@ # 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_static_path = ["_static"] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. @@ -291,3 +293,53 @@ # If true, do not generate a @detailmenu in the "Top" node's menu. # texinfo_no_detailmenu = False + + +# based on numpy doc/source/conf.py +def linkcode_resolve(domain, info): + """ + Determine the URL corresponding to Python object + """ + if domain != "py": + return None + + modname = info["module"] + fullname = info["fullname"] + + submod = sys.modules.get(modname) + if submod is None: + return None + + obj = submod + for part in fullname.split("."): + try: + obj = getattr(obj, part) + except AttributeError: + return None + + try: + fn = inspect.getsourcefile(inspect.unwrap(obj)) + except TypeError: + fn = None + if not fn: + return None + + try: + source, lineno = inspect.getsourcelines(obj) + except OSError: + lineno = None + + if lineno: + linespec = f"#L{lineno}-L{lineno + len(source) - 1}" + else: + linespec = "" + + fn = os.path.relpath(fn, start=os.path.dirname(xarray.__file__)) + + if "+" in xarray.__version__: + return f"https://github.com/xarray-contrib/datatree/blob/main/datatree/{fn}{linespec}" + else: + return ( + f"https://github.com/xarray-contrib/datatree/blob/" + f"v{datatree.__version__}/xarray/{fn}{linespec}" + ) diff --git a/docs/source/whats-new.rst b/docs/source/whats-new.rst index 71febcd9..18ac3024 100644 --- a/docs/source/whats-new.rst +++ b/docs/source/whats-new.rst @@ -48,6 +48,8 @@ Documentation - Added ``Reading and Writing Files`` page. (:pull:`158`) By `Tom Nicholas `_. +- Changed docs theme to match xarray's main documentation. (:pull:`173`) + By `Tom Nicholas `_. Internal Changes ~~~~~~~~~~~~~~~~