Merge pull request #3 from skoudoro/cleaning

Some Cleaning + initial github action

.github/workflows/pr-close.yml

@@ -0,0 +1,29 @@
+name: delete preview on PR close
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  delete_preview:
+    runs-on: ubuntu-latest
+    env:
+      PR_PATH: pull/${{github.event.number}}
+    steps:
+      - name: make empty dir
+        run: mkdir ${{ env.PR_PATH }}
+
+      - name: delete folder
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ${{ env.PR_PATH }}
+          destination_dir: ${{ env.PR_PATH }}
+
+      - name: Comment on PR
+        uses: hasura/[email protected]
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
+          number: ${{ github.event.number }}
+          id: deploy-preview
+          message: "🪓 PR closed, deleted preview at https://github.com/${{ github.repository }}/tree/gh-pages/${{ env.PR_PATH }}/"

.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: github pages
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+  schedule:
+    - cron: '0 0 * * 1'
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+        PR_PATH: pull/${{github.event.number}}
+    steps:
+      - name: Comment on PR
+        uses: hasura/[email protected]
+        if: github.ref != 'refs/heads/master'
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
+          number: ${{ github.event.number }}
+          id: deploy-preview
+          message: "Starting deployment of preview ⏳..."
+
+      - name: Checkout website repo
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+    #   - name: Install dependencies
+    #     run: |
+    #       python -m pip install --upgrade pip
+    #       pip install -r requirements.txt
+
+      - name: Build website
+        uses: ammaraskar/sphinx-action@master
+        with:
+            docs-folder: "."
+
+      - name: Upload HTML
+        uses: actions/upload-artifact@v1
+        with:
+            name: DocumentationHTML
+            path: _build/html/

Makefile

@@ -28,7 +28,6 @@ help:
 
 clean:
 	-rm -rf _build/*
-	-rm *-stamp
 
 gitwash-update:
 	python ../tools/gitwash_dumper.py devel dipy --repo-name=dipy --github-user=dipy \
@@ -71,9 +70,7 @@ qthelp:
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile _build/qthelp/dipy.qhc"
 
-latex: rstexamples latex-after-examples
-
-latex-after-examples:
+latex:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in _build/latex."
@@ -95,22 +92,3 @@ doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in _build/doctest/output.txt."
-
-rstexamples: rstexamples-stamp
-rstexamples-stamp:
-	cd examples_built && ../../tools/make_examples.py
-	touch $@
-
-pdf: pdf-stamp
-pdf-stamp: latex
-	cd _build/latex && make all-pdf
-	touch $@
-
-upload: html
-	./upload-gh-pages.sh _build/html/ dipy dipy
-
-xvfb:
-	export TEST_WITH_XVFB=true && make html
-
-memory_profile:
-	export TEST_WITH_MEMPROF=true && make html

README.md

@@ -1,24 +1,27 @@
-# Documentation Generation
+# DIPY.ORG
 
+## Background
+
+This site makes use of [Sphinx](https://www.sphinx-doc.org/en/stable/) and was built upon [Bootstrap](https://getbootstrap.com) via the [GRG Sphinx theme](https://github.com/GRG-Projects/grg-sphinx-theme) and [PYData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/).
+We use Github Action to deploy the website and Github Page to host the [website](https://dipy.org.github.io).
 ## Index
 
-- `_static`: Contains images, css, js for Sphinx to look at
-- `_templates`: Contains html layout for custom Sphinx design
-- `build`: Contains the generated documentation
-- `devel`: Contains `*.rst` files for the Developer's Guide
-- `examples`: DIPY application showcases. Add any tutorial here
-- `examples_built`: Keep it empty. Only for example generation
-- `releases_notes`: Contains all API changes / PRs, issues resolved for a specific release
-- `sphinxext`: Sphinx custom plugins
-- `theory`: Diffusion theory + FAQ files
-- `tools`: Scripts to generate some parts of the documentation, like the API
+- `_static`: Contains all assets (images, CSS, JS) for Sphinx to look at.
+- `_templates`: Contains html layout for custom Sphinx design.
+- `_build`: Contains the generated documentation.
+- `sphinxext`: Sphinx custom plugins.
+- `theory`: Diffusion theory + FAQ files.
+- `tools`: Contains all scripts to generate some parts of the documentation, like the API.
+- `posts`: Contains all blog posts.
 
-## Doc generation steps:
+## Testing Locally: Doc generation steps:
 
 ### Installing requirements
 
+To set up your computer to run this site locally, you need to install the various Python packages in the [requirements.txt](requirements.txt) at the top level of this repository.
+
 ```bash
-$ pip install -U -r doc-requirements.txt
+$ pip install -U -r requirements.txt
 ```
 
 ### Generate all the Documentation
@@ -35,3 +38,123 @@ $ make -C . clean && make -C . html
 $ ./make.bat clean
 $ ./make.bat html
 ```
+
+This will build a collection of html pages under `_build/html` and you can open the `index.html` using your browser of choice.
+
+## Creating a PR
+
+When you are happy with any changes you have made to the website.
+We recommend building the website and making sure that everything is building fine.
+You should see no warnings for the build.
+
+Once you are sure everything is in order, you can send a PR to this repository.
+If you are unfamiliar with this, please see this guide from [GitHub.](https://help.github.com/articles/about-pull-requests/)
+
+## PR Review
+
+When a PR is opened, Github Action will create a preview of any content or style changes.
+
+This must pass before the PR will be merged, furthermore, one review is required before a PR can be merged as well.
+
+## Creating a Blog Post
+
+Blog posts can be added by creating a new text file in the `posts/<current year>` directory.
+The filename must use the following naming convention `YEAR-MONTH-DAY-title.{ext}` and be written in one of the following formats:
+
+- [RST](https://www.sphinx-doc.org/en/stable/rest.html) formatted text, `ext=rst`,
+- [Jupyter notebook](https://jupyter.org/), `ext=ipynb`; (notebooks are converted to RST using the [nbsphinx](https://nbsphinx.readthedocs.io) extension)
+- [MD](https://www.markdownguide.org/cheat-sheet/) formatted text, `ext=md`,
+
+Please also see the [ABlog documentation](https://ablog.readthedocs.io/) for more information.
+
+### RST
+
+If you write your post in RST formatted text, each file must also contain the following header for Sphinx via [Ablog](https://github.com/sunpy/ablog) to parse the post properly:
+
+```rst
+.. post:: <Date>
+   :author: <Name>
+   :tags: <Tag list with commas>
+   :category: <One of the below>
+
+<Title>
+=========
+
+```
+
+or
+
+```rst
+:blogpost: true
+:date: <Date>
+:author: <Name>
+:category: <One of the below>
+
+<Title>
+=========
+
+```
+
+### Jupyter Notebook
+
+When writing posts as Jupyter notebooks, the first cell should be a Markdown cell with the title as a top-level heading (i.e. using a single `#`) and the second cell should be a raw cell containing the following
+
+```rst
+.. post:: <Date>
+   :author: <Name>
+   :tags: <Tag list with commas>
+   :category: <One of the below>
+   :exclude:
+
+   <Short description of post>
+```
+
+The short description will appear as a preview of your post on the blog page.
+See the [nbsphinx docs](https://nbsphinx.readthedocs.io/raw-cells.html) for information on making raw notebook cells compatible with Sphinx and RST.
+
+You might have to open the notebook in a text editor and change the "metadata" for the post cell to include the following
+
+```
+   "metadata": {
+    "raw_mimetype": "text/restructuredtext"
+   },
+```
+
+In theory the alternative rst style and the below markdown style should also work in this cell.
+
+Additionally, Sphinx will automatically add a link to the interactive version of your notebook, hosted on [Binder](https://mybinder.org/), to the top of your post.
+If your notebook requires any other dependencies besides SunPy (or its dependencies), they will need to be added to `binder/requirements.txt`.
+
+### Markdown
+
+If you write your post in markdown formatted text, each file must contain the following header for Sphinx via [Ablog](https://github.com/sunpy/ablog) to parse the post properly:
+
+```
+---
+blogpost: true
+date: <Date>
+author: <Name>
+category: <One of the below>
+---
+
+# <Title>
+
+```
+
+### Metadata
+
+Please note that the date for the post is different from the way it is written for the blog filename.
+Since this date is reader-facing, we want month day year **e.g.,** May 14 2056.
+
+The current range of categories we have "officially" are:
+
+- release
+- update
+- gsoc
+- news
+- tutorial
+- event
+
+Please select the more appropriate one, for many `update` or `news` would be enough.
+
+For tags, you can choose what you prefer for your post but please don't use any that are in the categories list.

blog.rst

@@ -0,0 +1,3 @@
+====
+Blog
+====

conf.py

@@ -37,7 +37,7 @@
               'github',
               'ablog',
               'jinja'
-]
+              ]
 
 # ghissue config
 github_project_url = "https://github.com/dipy/dipy.org"

documentation.rst

@@ -10,26 +10,9 @@ Documentation
    introduction
    mission
    installation
-   data
-   examples_built/index
-   interfaces/index
    faq
    developers
-   cite
-   devel/index
-   theory/index
-   reference/index
-   reference_cmd/index
-   api_changes
 
 .. Main content will be displayed using the jinja template
 
 
-..
-   Indices and tables
-   ==================
-
-   * :ref:`genindex`
-   * :ref:`modindex`
-   * :ref:`search`
-

glossary.rst

@@ -6,7 +6,7 @@
 
    Affine matrix
       A matrix implementing an :term:`affine transformation` in
-      :term:`homogenous coordinates`.  For a 3 dimensional transform, the
+      :term:`Homogeneous coordinates`.  For a 3 dimensional transform, the
       matrix is shape 4 by 4.
 
    Affine transformation

index.rst

@@ -79,7 +79,7 @@ As an exercise, you can try to calculate `color FA` with your datasets. You will
 to replace the filepaths `fdwi`, `fbval` and `fbvec`. Here is what
 a slice should look like.
 
-.. image:: _static/colorfa.png
+.. image:: _static/images/colorfa.png
     :align: center
 
 **********

introduction.rst

@@ -13,7 +13,7 @@ guidelines and try the :ref:`examples`. Didn't find what you are looking for?
 Then try :ref:`faq` and then if this doesn't help send an e-mail to our
 e-mail list [email protected] with subject starting with ``[DIPY]``.
 
-.. figure:: _static/pretty_tracks.png
+.. figure:: _static/images/pretty_tracks.png
    :align: center
 
    This is a depiction of tractography created with DIPY.