From 047d699408d191999bbbda5a77162cc4407264b5 Mon Sep 17 00:00:00 2001 From: "Martin K. Scherer" Date: Tue, 13 Jul 2021 13:38:33 +0200 Subject: [PATCH] Include markdown readme in sphinx index (#415) * use m2r2 to convert markdown to rst. * fix link in readme * removed "temporary" in docstr, as it is there for a long time already. * readme: sync title with documentation * restore repo status * fix * include readme.md directly in index.rst (also changelog) * use m2r2 in sphinx conf, do not copy changelog.md * revert asdf_schema_path * fix * minor fixes and build relative path * fix header level * try different static path for logos * revert old static paths * pin sphinx to 4.0 Co-authored-by: Cagtay Fabry <43667554+CagtayFabry@users.noreply.github.com> --- README.md | 10 +++--- doc/changelog_link.rst | 2 ++ doc/conf.py | 31 ++++++++-------- doc/index.rst | 76 +++++++++------------------------------ doc/rtd_environment.yml | 4 +-- weldx/welding/__init__.py | 2 +- 6 files changed, 41 insertions(+), 84 deletions(-) create mode 100644 doc/changelog_link.rst diff --git a/README.md b/README.md index 0c7105b31..0c0f1bd8e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# WelDX - Welding Data Exchange Format +# WelDX - data and quality standards for welding research data [![Documentation](https://readthedocs.org/projects/weldx/badge/?version=latest)](https://weldx.readthedocs.io/en/latest/?badge=latest) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/BAMWelDX/weldx/master?urlpath=lab/tree/tutorials/welding_example_01_basics.ipynb) @@ -29,7 +29,7 @@ WelDX provides several Python API to perform standard tasks like experiment desi ### Planning -- Define measurement chains with all involved devices, error sources, and meta data annotations. +- Define measurement chains with all involved devices, error sources, and metadata annotations. - Handle complex coordinate transformations needed to describe the movement of welding robots, workpieces, and sensors. - Planing of welding experiments. - convenient creation of [ISO 9692-1](https://www.iso.org/standard/62520.html) welding groove types. @@ -59,7 +59,7 @@ enables us to store the whole experimental pipeline performed in a modern labora We seek to provide a user-friendly, well documented programming interface. All functions and classes in WelDX have attached documentation about the involved parameters (types and explanation), see [API docs](https://weldx.readthedocs.io/en/stable/api.html). -Further we provide rich [Jupyter notebook tutorials](https://weldx.readthedocs.io/en/stable/tutorials.htm) about the handling of the basic workflows. +Further we provide rich [Jupyter notebook tutorials](https://weldx.readthedocs.io/en/stable/tutorials.html) about the handling of the basic workflows. All involved physical quantities used in weldX (lengths, angles, voltages, currents, etc.) should be attached with a unit to ensure automatic conversion and correct mathematical handling. Units are being used in all standard features @@ -69,7 +69,7 @@ of WelDX and are also archived in the ASDF files. This is implemented by the pop ## Installation The WelDX package can be installed using conda or mamba package manager from the :code:`conda-forge` channel. -These managers originate from the freely available [Anaconda Python stack](https://docs.conda.io/en/latest/miniconda.html>). +These managers originate from the freely available [Anaconda Python stack](https://docs.conda.io/en/latest/miniconda.html). If you do not have Anaconda or Miniconda installed yet, we ask you to install `Miniconda-3`. Documentation for the installation procedure can be found [here](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html#regular-installation). After this step you have access to the conda command and can proceed to installing the WelDX package. @@ -113,4 +113,4 @@ This research is funded by the Federal Ministry of Education and Research of Ger ### Documentation build [![Documentation Status](https://readthedocs.org/projects/weldx/badge/?version=latest)](https://weldx.readthedocs.io/en/latest/?badge=latest) -[![documentation](https://github.com/BAMWelDX/weldx/workflows/documentation/badge.svg?branch=master)](https://github.com/BAMWelDX/weldx/actions?query=workflow%3Adocumentation+branch%3Amaster) \ No newline at end of file +[![documentation](https://github.com/BAMWelDX/weldx/workflows/documentation/badge.svg?branch=master)](https://github.com/BAMWelDX/weldx/actions?query=workflow%3Adocumentation+branch%3Amaster) diff --git a/doc/changelog_link.rst b/doc/changelog_link.rst new file mode 100644 index 000000000..05d3e29fc --- /dev/null +++ b/doc/changelog_link.rst @@ -0,0 +1,2 @@ + +.. mdinclude:: ../CHANGELOG.md \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py index 615c0b611..4a2f49f2d 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -10,11 +10,11 @@ # -D nbsphinx_kernel_name="weldx" -D nbsphinx_execute="never" # -- 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 datetime import os import pathlib import shutil @@ -52,14 +52,10 @@ def _prevent_sphinx_circular_imports_bug(): except Exception as ex: raise -import weldx.visualization # load visualization -from weldx.asdf.constants import WELDX_TAG_BASE - -# -- copy files to doc folder ------------------------------------------------- -doc_dir = pathlib.Path(".") -changelog_file = pathlib.Path("./../CHANGELOG.md") -shutil.copy(changelog_file, doc_dir) +import weldx.visualization # load visualization (currently no auto-import in pkg). +from weldx.asdf.constants import SCHEMA_PATH, WELDX_TAG_BASE +# -- copy tutorial files to doc folder ------------------------------------------------- tutorials_dir = pathlib.Path("./tutorials") tutorial_files = pathlib.Path("./../tutorials/").glob("*.ipynb") for f in tutorial_files: @@ -67,9 +63,10 @@ def _prevent_sphinx_circular_imports_bug(): # -- Project information ----------------------------------------------------- +_now = datetime.datetime.now().year project = "weldx" -copyright = "2020 - 2021, BAM" +copyright = f"2020 - {_now}, BAM" author = "BAM" # The full version, including alpha/beta/rc tags @@ -85,7 +82,7 @@ def _prevent_sphinx_circular_imports_bug(): # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - "recommonmark", + "m2r2", "sphinxcontrib.napoleon", "nbsphinx", "sphinx.ext.autodoc", @@ -196,7 +193,7 @@ def _prevent_sphinx_circular_imports_bug(): # -- sphinx-asdf configuration ------------------------------------------------- # This variable indicates the top-level directory containing schemas. # The path is relative to the location of conf.py in the package -asdf_schema_path = "../weldx/asdf/schemas" +asdf_schema_path = os.path.relpath(SCHEMA_PATH) # This variable indicates the standard prefix that is common to all schemas # provided by the package. asdf_schema_standard_prefix = "weldx.bam.de/weldx" @@ -231,16 +228,16 @@ def _prevent_sphinx_circular_imports_bug(): # html_theme = "pydata_sphinx_theme" +# The name of an image file (relative to html_static_path) to place at the top +# of the sidebar. +html_logo = "_static/WelDX_notext.svg" +html_favicon = "_static/WelDX_notext.ico" + # 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"] -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -html_logo = "_static/WelDX_notext.svg" -html_favicon = "_static/WelDX_notext.ico" - html_theme_options = { # "external_links": [{"url": "https://asdf.readthedocs.io/", "name": "ASDF"}], "github_url": "https://github.com/BAMWelDX/weldx", diff --git a/doc/index.rst b/doc/index.rst index 20d3fb0d6..8a054b2df 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,61 +1,4 @@ -============================================================ -WelDX - data and quality standards for welding research data -============================================================ - -.. meta:: - :description lang=en: Scientific data format and Python API for welding research data. Setup your experiment and capture data in a single file. - :keywords: welding, weld, data format, archive, scientific data, experiment, visualization, GMAW, quality standard, objectivity, comparability, reproducibility, measurement chain, research data management - -.. meta:: - :google-site-verification: YvWuHWCE9tERkKT7KQejAwHM2cJVSfDewd5IzGZxDsU - -Introduction -############ -Scientific welding data covers a wide range of physical domains and timescales and are measured using various different sensors. -Complex and highly specialized experimental setups at different welding institutes complicate the exchange of welding research data further. - -The WelDX research project aims to foster the exchange of scientific data inside the welding community by developing and establishing a new open source file format suitable for documentation of experimental welding data and upholding associated quality standards. -In addition to fostering scientific collaboration inside the national and international welding community an associated advisory committee will be established to oversee the future development of the file format. -The proposed file format will be developed with regards to current needs of the community regarding interoperability, data quality and performance and will be published under an appropriate open source license. -By using the file format objectivity, comparability and reproducibility across different experimental setups can be improved. - -The project is under active development by the `Welding Technology `_ division at Bundesanstalt für Materialforschung und -prüfung (BAM). -Visit the projects site at `BAM `_. - -Python API -########## -The first core component of the ``WelDX`` project is the Python API. -The API aims to provide a framework for describing welding experiments as well as working and analysing welding research data in Python. - -Head over to the :doc:`tutorials` section to see some examples. - - -WelDX file standard -################### -The second main component is the the ``WelDX`` file standard that is used to define the contents and layouts of welding research data. The file standard is based on the `ASDF standard `_ and consists of custom schema definitions for welding related experiments, measurements, equipment and applications. - -Installation -############ -The WelDX package can be installed using conda or mamba package manager from the :code:`conda-forge` channel. -These managers originate from the freely available `Anaconda Python stack `_. -If you do not have Anaconda or Miniconda installed yet, we ask you to install ``Miniconda-3``. -Documentation for the installation procedure can be found `here `_. After this step you have access to the conda command and can proceed to installing the WelDX package. - -:: - - conda install weldx -c conda-forge - - -The package is also available on pypi. - -:: - - pip install weldx - - -Funding -####### -This research is funded by the Federal Ministry of Education and Research of Germany under project number 16QK12. +.. mdinclude:: ../README.md .. toctree:: :hidden: @@ -64,6 +7,21 @@ This research is funded by the Federal Ministry of Education and Research of Ger tutorials standard api - CHANGELOG + changelog_link legal-notice + +Python API +---------- + +The first core component of the ``WelDX`` project is the Python API. +The API aims to provide a framework for describing welding experiments as well as +working and analysing welding research data in Python. + +Head over to the :doc:`tutorials` section to see some examples. + + +.. meta:: + :description lang=en: Scientific data format and Python API for welding research data. Setup your experiment and capture data in a single file. + :keywords: welding, weld, data format, archive, scientific data, experiment, visualization, GMAW, quality standard, objectivity, comparability, reproducibility, measurement chain, research data management + :google-site-verification: YvWuHWCE9tERkKT7KQejAwHM2cJVSfDewd5IzGZxDsU diff --git a/doc/rtd_environment.yml b/doc/rtd_environment.yml index bdf3f13e1..457289681 100644 --- a/doc/rtd_environment.yml +++ b/doc/rtd_environment.yml @@ -7,9 +7,9 @@ dependencies: - ipykernel - ipywidgets # documentation - - sphinx + - sphinx=4.0 - jinja2=2 - - recommonmark + - m2r2 - sphinxcontrib-napoleon - nbsphinx - sphinx-copybutton diff --git a/weldx/welding/__init__.py b/weldx/welding/__init__.py index b44675e6d..6db8dfdfb 100644 --- a/weldx/welding/__init__.py +++ b/weldx/welding/__init__.py @@ -1,3 +1,3 @@ -"""Temporary module for welding related classes.""" +"""Module for welding related classes.""" from . import groove, processes, util