agaric/documentation
10
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Convert documentation page on documentation to MyST from RST

Browse source
This commit is contained in:
benjamin melançon 2020-08-04 07:27:29 -04:00
parent 63b5291833
commit df8d6404c2
2 changed files with 37 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

37
documentation.md Normal file
View file

@ -0,0 +1,37 @@
# Documentation
Welcome to the meta section of our documentation where we document how to do documentation!
Edit or add. That's the primary instruction. You can edit directly on [gitlab.com/agaric/documentation](https://gitlab.com/agaric/documentation) (for example, the edit link on this page takes you to [gitlab.com/agaric/documentation/blob/master/documentation.md](https://gitlab.com/agaric/documentation/blob/master/documentation.md)). If you aren't a member of Agaric, GitLab will helpfully offer to fork the documentation to your own namespace so that you can make a merge request with your documentation suggestion.
```{note}
This documentation page is a good one to copy or refer to as an example for ReStructuredText formatting. And of course anyone can come and clean up formatting later.
```
Where to post what
------------------
We like [Gitlab's approach](https://about.gitlab.com/handbook/git-page-update/#where-should-content-go): If you're not sure where to put something in documentation, or if it even is documentation, [write a blog post](https://agaric.com/node/add/blog). Or even, in the Agaric context, just throw it in a [raw note](https://gitlab.com/agaric/resources/raw-notes) (this private repository automatically publishes non-draft notes publicly to [agaric.gitlab.io/raw-notes](https://agaric.gitlab.io/raw-notes/)).
Somewhere is better than nowhere.
Don't worry about [translation](translation).
Guidelines
++++++++++
* Document closest to where people work:
* In README.md files or otherwise in the code repository for developers.
* In the site itself for site managers and content editors, or alternatively in an organization's already established locations.
* Topics which are of general application can be abstracted, put in this repository, and linked to at this documentation.
```{note}
In doing documentation we are living our [values](values) of encouraging continuous learning, appreciating new ideas, giving back to the communities we are part of, and valuing long-term relationships.
```
Running this documentation locally:
```bash
sphinx-build -b html . _build/html
```

37
documentation.rst
View file

@ -1,37 +0,0 @@
.. _documentation:
Documentation
=============
Welcome to the meta section of our documentation where we document how to do documentation!
Edit or add. That's the primary instruction. You can edit directly on `gitlab.com/agaric/documentation <https://gitlab.com/agaric/documentation>`_ (for example, the edit link on this page takes you to `gitlab.com/agaric/documentation/blob/master/documentation.rst <https://gitlab.com/agaric/documentation/blob/master/documentation.rst>`_). If you aren't a member of Agaric, GitLab will helpfully offer to fork the documentation to your own namespace so that you can make a merge request with your documentation suggestion.
.. note::
This documentation page is a good one to copy or refer to as an example for ReStructuredText formatting. And of course anyone can come and clean up formatting later.
Where to post what
------------------
We like `Gitlab's approach <https://about.gitlab.com/handbook/git-page-update/#where-should-content-go>`_: If you're not sure where to put something in documentation, or if it even is documentation, `write a blog post <https://agaric.com/node/add/blog>`_. Or even, in the Agaric context, just throw it in a `raw note <https://gitlab.com/agaric/resources/raw-notes>`_ (a private repository but non-draft notes are published to `agaric.gitlab.io/raw-notes <https://agaric.gitlab.io/raw-notes/>`_).
Somewhere is better than nowhere.
Don't worry about `translation <translation>`_ or :ref:`translation`
Guidelines
++++++++++
* Document closest to where people work:
* In README.md files or otherwise in the code repository for developers.
* In the site itself for site managers and content editors, or alternatively in an organization's already established locations.
* Topics which are of general application can be abstracted, put in this repository, and linked to at this documentation.
.. note::
In doing documentation we are living our :ref:`values` of encouraging continuous learning, appreciating new ideas, giving back to the communities we are part of, and valuing long-term relationships.
Running this documentation locally:
sphinx-build -b html . _build/html