diff --git a/front_matter/doc_editing_setup.md b/front_matter/doc_editing_setup.md deleted file mode 100644 index 067ce2f..0000000 --- a/front_matter/doc_editing_setup.md +++ /dev/null @@ -1,19 +0,0 @@ -# Documentation Editing Setup - -The documentation uses the [MyST](https://mystmd.org/) markup language. - -Install the following packages within an existing conda environment: -```{code} bash -conda install conda-forge::mystmd -conda install conda-forge::nodejs -conda install conda-forge::texlive-core -conda install conda-forge::latexmk -``` - -Check that MyST has been installed successfully by running -```{code} bash -myst -v -``` - -Run `myst` to render the documentation and click the local URL displayed on the terminal. -When editing source files, the local build will update automatically. diff --git a/front_matter/how_to_write_docs.md b/front_matter/how_to_write_docs.md new file mode 100644 index 0000000..bfe3c40 --- /dev/null +++ b/front_matter/how_to_write_docs.md @@ -0,0 +1,42 @@ +# How to Write Documentation + +The documentation uses the [MyST](https://mystmd.org/) markup language. + +In order to edit and view the documentation locally, please first install MyST following [MyST's installation instructions](https://mystmd.org/guide/installing). + +Check that MyST has been installed successfully by running +```{code} bash +myst --version +``` +Once MyST has been installed, run +```{code} bash +myst start +``` +from the root directory of the repository (where the MyST configuration file `myst.yml` is located) to start MyST locally. +This will display something like +```{code} bash +$ myst start + +📖 Built front_matter/introduction.md in 96 ms. +📖 Built front_matter/governance.md in 46 ms. +📖 Built front_matter/contributing.md in 45 ms. +📖 Built front_matter/doc_editing_setup.md in 45 ms. +📖 Built standard/introduction.md in 45 ms. +📖 Built standard/element_parameter.md in 44 ms. +📚 Built 6 pages for project in 193 ms. + + ✨✨✨ Starting Book Theme ✨✨✨ + +🔌 Server started on port 3000! 🥳 🎉 + + 👉 http://localhost:3000 👈 +``` + +Open the URL displayed in the terminal (in this case `http://localhost:3000`) to visualize the MyST content with your web browser. + +You are now ready to edit the markdown files that compose the documentation! +The content displayed in your web browser will update automatically as you edit. + +If you add new markdown files, do not forget to add them to the table of contents defined in the MyST configuration file `myst.yml`. + +Finally, once you are happy with your changes, do not forget to commit and push them to your branch and open a pull request on GitHub. diff --git a/myst.yml b/myst.yml index 27604a6..babfa3d 100644 --- a/myst.yml +++ b/myst.yml @@ -11,10 +11,9 @@ project: - file: 'front_matter/introduction.md' - title: 'Front Matter' children: - - file: 'front_matter/organization.md' - file: 'front_matter/governance.md' - file: 'front_matter/contributing.md' - - file: 'front_matter/doc_editing_setup.md' + - file: 'front_matter/how_to_write_docs.md' - title: 'Lattice Standard' children: - file: 'standard/introduction.md'