📚👌 Convert docs from RST to MD

CONTRIBUTING.md

@@ -0,0 +1,122 @@
+```{highlight} shell
+
+```
+
+# Contributing
+
+Contributions are welcome, and they are greatly appreciated! Every little bit
+helps, and credit will always be given.
+
+You can contribute in many ways:
+
+## Types of Contributions
+
+### Report Bugs
+
+Report bugs at <https://github.com/glotaran/pyglotaran-extras/issues>.
+
+If you are reporting a bug, please include:
+
+- Your operating system name and version.
+- Any details about your local setup that might be helpful in troubleshooting.
+- Detailed steps to reproduce the bug.
+
+### Fix Bugs
+
+Look through the GitHub issues for bugs. Anything tagged with "bug" and "help
+wanted" is open to whoever wants to implement it.
+
+### Implement Features
+
+Look through the GitHub issues for features. Anything tagged with "enhancement"
+and "help wanted" is open to whoever wants to implement it.
+
+### Write Documentation
+
+pyglotaran_extras could always use more documentation, whether as part of the
+official pyglotaran_extras docs, in docstrings, or even on the web in blog posts,
+articles, and such.
+
+### Submit Feedback
+
+The best way to send feedback is to file an issue at <https://github.com/glotaran/pyglotaran-extras/issues>.
+
+If you are proposing a feature:
+
+- Explain in detail how it would work.
+- Keep the scope as narrow as possible, to make it easier to implement.
+- Remember that this is a volunteer-driven project, and that contributions
+  are welcome :)
+
+## Get Started!
+
+Ready to contribute? Here's how to set up `pyglotaran_extras` for local development.
+
+1. Fork the `pyglotaran-extras` repo on GitHub.
+
+2. Clone your fork locally:
+
+   ```
+   $ git clone git@github.com:your_name_here/pyglotaran_extras.git
+   ```
+
+3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:
+
+   ```
+   $ mkvirtualenv pyglotaran_extras
+   $ cd pyglotaran-extras/
+   $ pip install -e .
+   ```
+
+4. install the `pre-commit` and `pre-push` hooks:
+
+   ```
+   $ pre-commit install && pre-commit install -t pre-push
+   ```
+
+5. Create a branch for local development:
+
+   ```
+   $ git checkout -b name-of-your-bugfix-or-feature
+   ```
+
+   Now you can make your changes locally.
+
+6. When you're done making changes, check that your changes pass flake8 and the
+   tests, including testing other Python versions with tox:
+
+   ```
+   $ tox
+   ```
+
+   To get flake8 and tox, just pip install them into your virtualenv.
+
+7. Commit your changes and push your branch to GitHub:
+
+   ```
+   $ git add .
+   $ git commit -m "Your detailed description of your changes."
+   $ git push origin name-of-your-bugfix-or-feature
+   ```
+
+8. Submit a pull request through the GitHub website.
+
+## Pull Request Guidelines
+
+Before you submit a pull request, check that it meets these guidelines:
+
+1. The pull request should include tests.
+2. If the pull request adds functionality, the docs should be updated. Put
+   your new functionality into a function with a docstring, and add the
+   feature to the list in README.md.
+3. The pull request should work for Python 3.10 and 3.11. Check
+   <https://github.com/glotaran/pyglotaran-extras/actions>
+   and make sure that the tests pass for all supported Python versions.
+
+## Tips
+
+To run a subset of tests:
+
+```
+$ pytest tests.test_pyglotaran_extras
+```

docs/api_docs.md

@@ -0,0 +1,11 @@
+# Inner workings
+
+This is the detailed documentation of the inner workings of `pyglotaran_extras`.
+
+```{eval-rst}
+.. autosummary::
+    :toctree: api
+    :recursive:
+
+    pyglotaran_extras
+```

docs/conf.py

@@ -78,7 +78,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/contributing.md

@@ -0,0 +1,3 @@
+```{include} ../CONTRIBUTING.md
+
+```

docs/index.md

@@ -0,0 +1,19 @@
+# Welcome to pyglotaran_extras's documentation!
+
+```{toctree}
+:caption: 'Contents:'
+:maxdepth: 2
+
+readme
+installation
+usage
+api_docs
+contributing
+changelog
+```
+
+## Indices and tables
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`

docs/installation.md

@@ -0,0 +1,45 @@
+```{highlight} shell
+
+```
+
+# Installation
+
+## Stable release
+
+To install pyglotaran_extras, run this command in your terminal:
+
+```console
+$ pip install pyglotaran_extras
+```
+
+This is the preferred method to install pyglotaran_extras, as it will always install the most recent stable release.
+
+If you don't have [pip] installed, this [Python installation guide] can guide
+you through the process.
+
+## From sources
+
+The sources for pyglotaran_extras can be downloaded from the [Github repo].
+
+You can either clone the public repository:
+
+```console
+$ git clone git://github.com/glotaran/pyglotaran-extras
+```
+
+Or download the [tarball]:
+
+```console
+$ curl -OJL https://github.com/glotaran/pyglotaran-extras/tarball/main
+```
+
+Once you have a copy of the source, you can install it with:
+
+```console
+$ pip install .
+```
+
+[github repo]: https://github.com/glotaran/pyglotaran-extras
+[pip]: https://pip.pypa.io
+[python installation guide]: http://docs.python-guide.org/en/latest/starting/installation/
+[tarball]: https://github.com/glotaran/pyglotaran-extras/tarball/main