Merge pull request wannier-developers#483 from qiaojunfeng/mdlint

Add markdownlint to pre-commit

.markdownlint.yaml

@@ -0,0 +1,20 @@
+# config file markdownlint-cli2
+
+# MD007/ul-indent : Unordered list indentation : https://github.com/DavidAnson/markdownlint/blob/main/doc/md007.md
+# this is to make sure mkdocs can correctly render nested lists
+MD007:
+  # Spaces for indent
+  indent: 4
+
+# MD033/no-inline-html : Inline HTML : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md033.md
+MD033:
+  allowed_elements:
+    - br
+    - figure
+    - table
+    - figcaption
+    - em
+    - sub
+    - a
+    - sup
+    - code

.pre-commit-config.yaml

@@ -31,3 +31,11 @@ repos:
         pwscf/.*
       )$
     verbose: true
+- repo: https://github.com/DavidAnson/markdownlint-cli2
+  rev: v0.12.1
+  hooks:
+  - id: markdownlint-cli2
+    args: ['--fix']
+    files: (?x)^(
+        docs/.*
+      )$

docs/README.md

@@ -4,10 +4,12 @@ Wannier90 documentation using `mkdocs`.
 
 ## Project layout
 
-    mkdocs.yml    # The configuration file.
-    docs/
-        index.md  # The documentation homepage.
-        ...       # Other markdown pages, images and other files.
+```bash
+mkdocs.yml    # The configuration file.
+docs/
+    index.md  # The documentation homepage.
+    ...       # Other markdown pages, images and other files.
+```
 
 ## Installation
 
@@ -24,7 +26,9 @@ pip install -r requirements.txt
 
 ## Notes on conversion
 
-The original wannier90 latex documentation was converted to markdown using `pandoc`. The resulting markdown files were then manually edited to fit the `mkdocs` format.
+The original wannier90 latex documentation was converted to markdown using
+`pandoc`. The resulting markdown files were then manually edited to fit the
+`mkdocs` format.
 
 ```bash
 pandoc -s wannier90/doc/user_guide/user_guide.tex -o user_guide.md

docs/docs/index.md

@@ -2,7 +2,8 @@
 
 ![Wannier90 logo](assets/wannier-logo.svg){ width=400 }
 
-This is the home of the documenation of [Wannier90](https://wannier.org), which a computer program for maximally-localised Wannier functions (MLWFs).
+This is the home of the documenation of [Wannier90](https://wannier.org),
+which a computer program for maximally-localised Wannier functions (MLWFs).
 
 - [User guide](user_guide/introduction.md)
 - [Tutorials](tutorials/preliminaries.md)

docs/docs/tutorials/preliminaries.md

@@ -1,52 +1,44 @@
----
-author:
-- Version 3.1
-bibliography:
-- ../wannier90.bib
-title: ": Tutorials"
----
-
-# Preliminaries {#preliminaries .unnumbered}
+# Preliminaries
 
 Welcome to `wannier90`! The examples contained in these tutorials are
 designed to help you become familiar with the procedure of generating,
 analysing and using maximally-localised Wannier functions (MLWFs). As a
 first step, install `wannier90` following the instructions in the
-` README` file of the `wannier90` distribution. For an introduction to
+`README` file of the `wannier90` distribution. For an introduction to
 the theory underlying MLWFs, you are encouraged to refer to the brief
-overview given in the `wannier90` User Guide [@UserGuide], to the two
-seminal papers of Refs. [@marzari-prb97; @souza-prb01], a recent review
-article [@marzari-rmp12] and to a paper [@mostofi-cpc08] describing
+overview given in the `wannier90` [User Guide](../user_guide/introduction.md),
+to the two seminal papers of Refs. [@marzari-prb97; @souza-prb01], a recent
+review article [@marzari-rmp12] and to a paper [@mostofi-cpc08] describing
 `wannier90`.
 
 The following additional programs may be installed in order to visualise
 the output of `wannier90` (they are optional, not all of them are
 necessary)
 
--   `gnuplot` is used to plot bandstructures. It is available for many
+- `gnuplot` is used to plot bandstructures. It is available for many
     operating systems and is often installed by default on Unix/Linux
     distributions <br>
     <http://www.gnuplot.info>
 
--   `xmgrace` may also be used to plot bandstructures.<br>
+- `xmgrace` may also be used to plot bandstructures.<br>
     <http://plasma-gate.weizmann.ac.il/Grace>
 
--   `XCrySDen` is used to visualise crystal structures, MLWFs, and Fermi
+- `XCrySDen` is used to visualise crystal structures, MLWFs, and Fermi
     surfaces. It is available for Unix/Linux, Windows (using cygwin),
     and OSX. To correctly display files from `wannier90`, version 1.4 or
     later must be used.<br>
     <http://www.xcrysden.org>
 
--   `vmd` can also be used to visualise crystal structures and MLWFs.<br>
+- `vmd` can also be used to visualise crystal structures and MLWFs.<br>
     <http://www.ks.uiuc.edu/Research/vmd>
 
--   `python` with the `numpy` and `matplotlib` modules is used in
+- `python` with the `numpy` and `matplotlib` modules is used in
     tutorials 17 &#151; 19<br>
     <http://www.python.org><br>
     <http://www.numpy.org><br>
     <http://matplotlib.org>
 
-# Parallel execution {#parallel-execution .unnumbered}
+## Parallel execution
 
 `postw90.x` and `wannier90.x` can
 be run in parallel to speed up the calculations, using the MPI
@@ -68,7 +60,7 @@ mpirun -np 8 postw90.x seedname
 libraries installed on your system: refer to your MPI manual and/or to
 your system administrator for further information).
 
-# About these tutorials {#about-this-tutorials .unnumbered}
+## About these tutorials
 
 The first part of this collection of tutorials comprises four examples taken from
 Refs. [@marzari-prb97; @souza-prb01]: gallium arsenide, lead, silicon
@@ -79,7 +71,7 @@ The second part of this collection of tutorials covers the generation of
 calculation. We have provided input files for the
 `pwscf` interface (<http://www.quantum-espresso.org>) to
 `wannier90`. Therefore, you will need to install and compile elements of
-the ` quantum-espresso` package, namely `pw.x` and ` pw2wannier90.x`, in
+the `quantum-espresso` package, namely `pw.x` and `pw2wannier90.x`, in
 order to run these tutorials. Please visit
 <http://www.quantum-espresso.org> to download the package, and for
 installation instructions. The tutorials work with
@@ -98,13 +90,13 @@ including abinit (<http://www.abinit.org>), fleur
 (<https://wiki.fysik.dtu.dk/gpaw/>), VASP (<http://www.vasp.at>), and
 Wien2k (<http://www.wien2k.at>)
 
-# Contact us {#contact-us .unnumbered}
+## Contact us
 
 If you have any suggestions regarding ways in which these tutorials may be
 improved, then send us an email.
 
 For other questions, email the `wannier90` forum at
-` wannier@quantum-espresso.org`. Note that first you will need to
+`wannier@quantum-espresso.org`. Note that first you will need to
 register in order to post emails. Emails from non-registered users are
 deleted automatically. You can register by following the links at
 <http://www.wannier.org/forum.html>.

docs/docs/tutorials/tutorial_1.md

@@ -1,28 +1,28 @@
-# 1: Gallium Arsenide — MLWFs for the valence bands {#gallium-arsenide-mlwfs-for-the-valence-bands .unnumbered}
+# 1: Gallium Arsenide — MLWFs for the valence bands
 
--   Outline: *Obtain and plot MLWFs for the four valence bands of GaAs.*
+- Outline: *Obtain and plot MLWFs for the four valence bands of GaAs.*
 
--   Generation details: *From `pwscf`, using norm-conserving
-    pseudopotentials and a <br> 
+- Generation details: *From `pwscf`, using norm-conserving
+    pseudopotentials and a <br>
     2$\times$2$\times$2 k-point grid. Starting guess: four bond-centred Gaussians.*
 
--   Directory: `tutorials/tutorial01/` *Files can be downloaded from 
+- Directory: `tutorials/tutorial01/` *Files can be downloaded from
     [here](https://github.com/wannier-developers/wannier90/tree/develop/tutorials/tutorial01)*
 
--   Input Files
+- Input Files
 
-    -    `gaas.win` *The master input file*
+    - `gaas.win` *The master input file*
 
-    -    `gaas.mmn` *The overlap matrices
-        $\mathbf{M}^{(\mathbf{k},\mathbf{b})}$*
+    - `gaas.mmn` *The overlap matrices
+            $\mathbf{M}^{(\mathbf{k},\mathbf{b})}$*
 
-    -    `gaas.amn` *Projection $\mathbf{A}^{(\mathbf{k})}$ of the Bloch
-        states onto a set of trial localised orbitals*
+    - `gaas.amn` *Projection $\mathbf{A}^{(\mathbf{k})}$ of the Bloch
+            states onto a set of trial localised orbitals*
 
-    -    `UNK00001.1` *The Bloch states in the real space unit cell. For
-        plotting only.*
+    - `UNK00001.1` *The Bloch states in the real space unit cell. For
+            plotting only.*
 
-1.  Run `wannier90` to minimise the MLWFs spread
+1. Run `wannier90` to minimise the MLWFs spread
 
     ```bash title="Terminal"
     wannier90.x  gaas
@@ -36,24 +36,29 @@
     each k-point by just the 4$\times$4 unitary
     matrices $\mathbf{U}^{(\mathbf{k})}$.
 
-2.  Plot the MLWFs by adding the following keywords to the input file
+2. Plot the MLWFs by adding the following keywords to the input file
     `gaas.win`
 
     ```vi title="Input file"
     wannier_plot = true
     ```
 
     and re-running `wannier90`. To visualise the MLWFs we must represent
-    them explicitly on a real space grid (see the [User guide page](../user_guide/wannier90/methodology.md#methodology)). As a
-    consequence, plotting the MLWFs is slower and uses more memory than
+    them explicitly on a real space grid (see the
+    [User guide page](../user_guide/wannier90/methodology.md#methodology)).
+    As a consequence, plotting the MLWFs is slower and uses more memory than
     the minimisation of the spread. The four files that are created
-    (`gaas_00001.xsf`, etc.) can be viewed using `XCrySDen`[^1],
+    (`gaas_00001.xsf`, etc.) can be viewed using `XCrySDen`,
     e.g.,
 
     ```bash title="Terminal"
     xcrysden --xsf gaas_00001.xsf
     ```
 
+    !!! hint
+        Once `XCrySDen` starts, click on `Tools` $\rightarrow$ `Data Grid`
+        in order to specify an isosurface value to plot.
+
     For large systems, plotting the MLWFs may be time consuming and
     require a lot of memory. Use the keyword `wannier_plot_list` to plot
     a subset of the MLWFs. E.g., to plot the 1st and 3rd MLWFs use
@@ -63,7 +68,7 @@
     ```
 
     The MLWFs are plotted in a supercell of the unit cell. The size of
-    this supercell is set through the keyword ` wannier_plot_supercell`.
+    this supercell is set through the keyword `wannier_plot_supercell`.
     The default value is 2 (corresponding to a supercell with eight
     times the unit cell volume). We recommend not using values great
     than 3 as the memory and computational cost scales cubically with
@@ -72,9 +77,9 @@
     Plot the 3rd MLWFs in a supercell of size 3. Choose a low value for
     the isosurface (say 0.5). Can you explain what you see?
 
-    *Hint:* For a finite k-point mesh, the MLWFs are in fact periodic
-    and the period is related to the spacing of the k-point mesh. For
-    mesh with $n$ divisions in the $i^{\mathrm{th}}$ direction in the
-    Brillouin zone, the MLWFs "live" in a supercell $n$ times the unit
-    cell.
-    [^1]: http://www.xcrysden.org/
+    !!! hint
+        For a finite k-point mesh, the MLWFs are in fact periodic
+        and the period is related to the spacing of the k-point mesh. For
+        mesh with $n$ divisions in the $i^{\mathrm{th}}$ direction in the
+        Brillouin zone, the MLWFs "live" in a supercell $n$ times the unit
+        cell.

docs/docs/tutorials/tutorial_10.md

@@ -1,54 +1,52 @@
-# 10: Graphite {#graphite .unnumbered}
+# 10: Graphite
 
--   Outline: *Obtain MLWFs for graphite (AB, Bernal)*
+- Outline: *Obtain MLWFs for graphite (AB, Bernal)*
 
--   Directory: `tutorials/tutorial10/` *Files can be downloaded from 
+- Directory: `tutorials/tutorial10/` *Files can be downloaded from
     [here](https://github.com/wannier-developers/wannier90/tree/develop/tutorials/tutorial10)*
 
--   Input Files
+- Input Files
 
-    -    `graphite.scf` *The `pwscf` input file for ground
+    - `graphite.scf` *The `pwscf` input file for ground
         state calculation*
 
-    -    `graphite.nscf` *The `pwscf` input file to obtain
+    - `graphite.nscf` *The `pwscf` input file to obtain
         Bloch states on a uniform grid*
 
-    -    `graphite.pw2wan` *Input file for `pw2wannier90`*
+    - `graphite.pw2wan` *Input file for `pw2wannier90`*
 
-    -    `graphite.win` *The `wannier90` input file*
+    - `graphite.win` *The `wannier90` input file*
 
-1.  Run `pwscf` to obtain the ground state of graphite
+1. Run `pwscf` to obtain the ground state of graphite
 
     ```bash title="Terminal"
     pw.x < graphite.scf > scf.out
     ```
 
-2.  Run `pwscf` to obtain the Bloch states on a uniform
+2. Run `pwscf` to obtain the Bloch states on a uniform
     k-point grid
 
     ```bash title="Terminal"
     pw.x < graphite.nscf > nscf.out
     ```
 
-3.  Run `wannier90` to generate a list of the required overlaps (written
+3. Run `wannier90` to generate a list of the required overlaps (written
     into the `graphite.nnkp` file).
 
     ```bash title="Terminal"
     wannier90.x -pp graphite
     ```
 
-4.  Run `pw2wannier90` to compute the overlap between Bloch states and
+4. Run `pw2wannier90` to compute the overlap between Bloch states and
     the projections for the starting guess (written in the
     `graphite.mmn` and `graphite.amn` files).
 
     ```bash title="Terminal"
     pw2wannier90.x < graphite.pw2wan > pw2wan.out
     ```
 
-5.  Run `wannier90` to compute the MLWFs.
+5. Run `wannier90` to compute the MLWFs.
 
     ```bash title="Terminal"
     wannier90.x graphite
     ```
-
-