|
1 | | -# Setting up sphinx to create a matlab doc |
2 | | - |
3 | | -## Set up virtual environment |
4 | | - |
5 | | -```bash |
6 | | -virtualenv -p python3 cpp_spm |
7 | | -source cpp_spm/bin/activate |
8 | | - |
9 | | -pip install -r requirements.txt |
10 | | -``` |
11 | | - |
12 | | -## Quick start on the doc |
13 | | - |
14 | | -See the [sphinx doc](https://www.sphinx-doc.org/en/master/usage/quickstart.html) |
15 | | -for more. |
16 | | - |
17 | | -This |
18 | | -[blog post](https://medium.com/@richdayandnight/a-simple-tutorial-on-how-to-document-your-python-project-using-sphinx-and-rinohtype-177c22a15b5b) |
19 | | -is also useful. |
20 | | - |
21 | | -```bash |
22 | | -cd docs |
23 | | -sphinx-quickstart # launch a basic interactive set up of sphinx |
24 | | -``` |
25 | | - |
26 | | -Answer the questions on prompt. |
27 | | - |
28 | | -## Setting up conf.py for matlab doc |
29 | | - |
30 | | -Following the documentation from |
31 | | -[matlabdomain for sphinx](https://github.com/sphinx-contrib/matlabdomain). |
32 | | - |
33 | | -Specify the extensions you are using: |
34 | | - |
35 | | -```python |
36 | | -extensions = [ |
37 | | - 'sphinxcontrib.matlab', |
38 | | - 'sphinx.ext.autodoc'] |
39 | | -``` |
40 | | - |
41 | | -`matlab_src_dir` in `docs/source/conf.py` should have the path (relative to |
42 | | -`conf.py`) to the folder containing your matlab code: |
43 | | - |
44 | | -```python |
45 | | -matlab_src_dir = os.path.dirname(os.path.abspath('../../src')) |
46 | | -``` |
47 | | - |
48 | | -## reStructured text markup |
49 | | - |
50 | | -reStructured text mark up primers: |
51 | | - |
52 | | -- on the [sphinx site](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) |
53 | | - |
54 | | -- more |
55 | | - [python oriented](https://pythonhosted.org/an_example_pypi_project/sphinx.html) |
56 | | - |
57 | | -- typical doc strings templates |
58 | | - - [google way](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html) |
59 | | - - [numpy](https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html#example-numpy) |
60 | | - |
61 | | -## "Templates" |
62 | | - |
63 | | -The templates to use for the doc are in the `src/templates` folder. |
64 | | - |
65 | | -You then just need to insert this in your `.rst` file for the documentation to |
66 | | -be done automatically. |
67 | | - |
68 | | -```rst |
69 | | -
|
70 | | -.. automodule:: src.folder_name .. <-- This is necessary for auto-documenting the rest |
71 | | -
|
72 | | -.. autofunction:: function to document |
73 | | -
|
74 | | -``` |
75 | | - |
76 | | -To get the filenames of all the functions in a folder: |
77 | | - |
78 | | -``` bash |
79 | | -ls -l src/*.m | cut -c42- | rev | cut -c 3- | rev |
80 | | -``` |
81 | | - |
82 | | -Increase the `42` to crop more characters at the beginning. |
83 | | - |
84 | | -Change the `3` to crop more characters at the end. |
85 | | - |
86 | | -## Build the documentation locally |
87 | | - |
88 | | -From the `docs` directory: |
89 | | - |
90 | | -```bash |
91 | | -sphinx-build -b html source build |
92 | | -``` |
93 | | - |
94 | | -This will build an html version of the doc in the `build` folder. |
95 | | - |
96 | | -## Build the documentation with Read the Docs |
97 | | - |
98 | | -Add a [`.readthedocs.yml`](../.readthedocs.yml) file in the root of your repo. |
99 | | - |
100 | | -See [HERE](https://docs.readthedocs.io/en/stable/config-file/v2.html) for |
101 | | -details. |
102 | | - |
103 | | -You can then trigger the build of the doc by going to the |
104 | | -[read the docs website](https://readthedocs.org). |
105 | | - |
106 | | -You might need to be added as a maintainer of the doc. |
107 | | - |
108 | | -The doc can be built from any branch of a repo. |
| 1 | +Information on how to write and build the documentation can be found in our |
| 2 | +[CONTRIBUTING guidelines](https://github.com/cpp-lln-lab/.github/blob/main/CONTRIBUTING.md). |
0 commit comments