Merge pull request #51 from pyscal/update_docs

Update docs

.github/workflows/book.yml

@@ -0,0 +1,35 @@
+name: Jupyterbook
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    env:
+      CONDA_PREFIX: /usr/share/miniconda/
+
+    steps:
+    - uses: actions/checkout@v2
+    - uses: conda-incubator/setup-miniconda@v2
+      with:
+        python-version: "3.8"
+        mamba-version: "*"
+        channels: conda-forge,nodefaults
+        channel-priority: true
+        environment-file: environment.yml
+    - name: Install Jupyterbook
+      shell: bash -l {0}
+      run: |
+        jupyter-book build . --path-output public
+    - run: mv public/_build/html public_html
+    - run: touch public_html/.nojekyll
+    - name: Deploy 🚀
+      uses: JamesIves/[email protected]
+      with:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        BRANCH: gh-pages # The branch the action should deploy to.
+        FOLDER: public_html # The folder the action should deploy.
+        CLEAN: true

_config.yml

@@ -0,0 +1,52 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: "pyscal-rdf"
+#author: The Jupyter Book Community
+logo: docs/source/_static/logo.png
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: "auto"
+
+only_build_toc_files: true
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: book.tex
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/pyscal/pyscal_rdf
+  path_to_book: book
+  branch: main
+
+notebook_interface            : "notebook"
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: false
+  use_repository_button: true
+
+parse:
+  myst_enable_extensions:
+    # don't forget to list any other extensions you want enabled,
+    # including those that are enabled by default!
+    - html_image
+    - amsmath
+    - dollarmath
+    - linkify
+    - substitution
+    - colon_fence
+
+sphinx:
+  config:
+    mathjax_path: https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+    html_theme: pydata_sphinx_theme
+    html_js_files:
+      - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js
+    html_sidebars:
+      "**": []

_toc.yml

@@ -0,0 +1,15 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: docs/intro
+chapters:
+  - file: docs/gettingstarted.md
+  - file: docs/examples.md
+    sections:
+    - file: examples/01_getting_started
+    - file: examples/02_grain_boundaries
+  - file: docs/extending.md
+  - file: docs/license.md
+  - file: docs/acknowledgements.md
+

docs/acknowledgements.md

@@ -0,0 +1,16 @@
+# Acknowledgements
+
+## Developers
+
+-   [Sarath Menon](http://sarathmenon.me)  
+-   [Abril Azócar Guzmán](https://www.fz-juelich.de/profile/guzman_a.azocar)
+
+
+## Contributers
+
+Please see the complete list of contributers [here](https://github.com/pyscal/pyscal_rdf/graphs/contributors).
+
+
+## Acknowledgements
+
+Funding for this publication was provided by the NFDI consortium [NFDI-MatWerk](https://nfdi-matwerk.de/) in the context of the work of the association German National Research Data Infrastructure (NFDI) e.V. NFDI is financed by the Federal Republic of Germany and the 16 federal states and funded by the Federal Ministry of Education and Research (BMBF) - funding code M532701 / the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) - [project number 460247524](https://gepris.dfg.de/gepris/projekt/460247524?language=en).

docs/examples.md

@@ -0,0 +1,29 @@
+# Examples
+
+The gallery of examples below cover different ways in which pyscal-rdf can be used.
+
+::::{grid} 1 1 2 3
+:class-container: text-center
+:gutter: 3
+
+:::{grid-item-card}
+:link: ../examples/01_getting_started
+:link-type: doc
+:class-header: bg-light
+Getting started with pyscal-rdf
+^^^
+Learn the very basis, including the concepts of creating structures, and querying them.
+:::
+
+:::{grid-item-card}
+:link: ../examples/02_grain_boundaries
+:link-type: doc
+:class-header: bg-light
+Creating grain boundary structures
+^^^
+Create, visualize, query, and export grain boundary structures.
+:::
+
+::::
+
+

docs/extending.md

@@ -0,0 +1,67 @@
+
+# Support
+
+In case of bugs and feature improvements, you are welcome to create a
+new issue on the [github repo](https://github.com/pyscal/pyscal_rdf). You
+are also welcome to fix a bug or implement a feature. 
+
+Any other questions or suggestions are welcome, please contact
+[us](mailto:[email protected]).
+
+`pyscal-rdf` welcomes and appreciates contribution and extension to the
+module. Rather than local modifications, we request that the
+modifications be submitted through a pull request, so that the module
+can be continuously improved.
+
+## Reporting and fixing bugs
+
+In case a bug is found in the module, it can be reported on the [issues
+page of the repository](https://github.com/pyscal/pyscal_rdf/issues). Once a bug is reported, the status can once again monitored on
+the issues page. Additionally, you are of course very welcome to fix any
+existing bugs.
+
+## New features
+
+If you have an idea for new feature, you can submit a feature idea
+through the [issues page of the
+repository](https://github.com/pyscal/pyscal_rdf/issues). As much as
+information as you can provide about the new feauture would be greatly
+helpful. Additionally, you could also work on feature requests already
+on the issues page. The following instructions will help you get started
+with local feature development.
+
+### Setting up local environment
+
+1.  The first step is to fork `pyscal-rdf`. A detailed tutorial on forking can
+    be found [here](https://help.github.com/en/articles/fork-a-repo).
+    After forking, clone the repository to your local machine.
+2.  We recommend creating a virtual environment to test new features or
+    improvements to features. See this
+    [link](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)
+    for help on managing environments.
+3.  Once the environment is set up, you can create a new branch for your
+    feature by `git checkout -b new_feauture`.
+4.  Now implement the necessary feature.
+5.  Once done, you can reinstall `pyscal-rdf` by `pip install .`.
+    After that please make sure that the existing tests work by running
+    `pytest tests/` from the main module folder.
+6.  If the tests work, you are almost done! If the new feature is not
+    covered in existing tests, you can to write a new test in the tests
+    folder. `pyscal-rdf` uses pytest for tests. [This
+    link](http://doc.pytest.org/en/latest/getting-started.html) will
+    help you get started.
+7.  Add the necessary docstrings for the new functions implemented.
+    `pyscal-rdf` uses the [numpy docstring
+    format](https://numpydoc.readthedocs.io/en/latest/format.html) for
+    documentation.
+8.  Bonus task: Set up few examples that document how the feature works
+    in the `docs` folder and link it to the examples section.
+9.  Final step - Submit a pull request through github. Before you
+    submit, please make sure that the new feature is documented and has
+    tests. Once the request is submitted, automated tests would be done.
+    If all tests are successful, your feauture will be incorporated to calphy and your contributions
+    will be credited.
+
+If you have trouble with any of the steps, or you need help, please
+[send an email](mailto:[email protected]) and we will be happy to
+help! 

docs/source/gettingstarted.md → docs/gettingstarted.md

@@ -1,35 +1,35 @@
  # Installation
 
-### Supported operating systems
+`pyscal-rdf` can be installed on Linux and Mac OS based systems. On Windows systems, it is recommended to use  [Windows subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install). The following instructions will help install `pyscal-rdf`:
 
-`pyscal_rdf` can be installed on Linux and Mac OS based systems. On Windows systems, it is recommended to use  [Windows subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install).
+````{tab-set}
+```{tab-item} pip
+`pip install pyscal-rdf`
+```
 
-### Using a conda environment
+```{tab-item} conda
+`conda install -c conda-forge pyscal-rdf`
+```
 
+```{tab-item} from source
 We strongly recommend creating a conda environment for the installation. To see how you can install conda see [here](https://docs.conda.io/projects/conda/en/latest/user-guide/install/).
 
 Once a conda distribution is available, the following steps will help set up an environment to use `pyscal_rdf`. First step is to clone the repository.
 
-```
-git clone https://github.com/pyscal/pyscal_rdf.git
-```
+`git clone https://github.com/pyscal/pyscal_rdf.git`
 
 After cloning, an environment can be created from the included file-
 
-```
-cd pyscal_rdf
-conda env create -f environment.yml
-```
+`cd pyscal_rdf`  
+`conda env create -f environment.yml`
 
 This will install the necessary packages and create an environment called rdf. It can be activated by,
 
-```
-conda activate rdf
-```
+`conda activate rdf`
 
 then, install `pyscal_rdf` using,
 
+`pip install .`
 ```
-pip install .
-```
+````