-
Notifications
You must be signed in to change notification settings - Fork 39
/
readthedoc.txt
118 lines (76 loc) · 4.04 KB
/
readthedoc.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
===============================================
Publish your documentation with ReadTheDocs.org
===============================================
Prerequisites
=============
Your doc is written :)
Prepare the configuration file for Sphinx
=========================================
In the plugin repository, create a file **docs/conf.py** which contains: ::
import sys
import os
extensions = [
'sphinx.ext.todo',
]
source_suffix = '.txt'
master_doc = 'index'
### part to update ###################################
project = u'domogik-plugin-diskfree'
copyright = u'2014, Fritz'
version = '0.1'
release = version
######################################################
pygments_style = 'sphinx'
html_theme = 'default'
html_static_path = ['_static']
htmlhelp_basename = project
Update the middle part depending on your plugin.
Create an account on RTD
========================
If you don't have an account, go on RTD and create an account
Add your plugin project to RTD
==============================
`In the dashboard <https://readthedocs.org/dashboard/>`, click on **Import** to add your plugin documentation.
Fill the form:
* Name : put the full plugin name : *domogik-plugin-myplugin*.
* Repo : put the github repository url : *http://github.com/mygithublogin/domogik-plugin-myplugin.git*
* Repository type : Git or something else if you don't use git
* Description : your plugin description
* Language : English
* Documentation type : Sphinx html
* Project url : empty
* Canonical url : empty
* Tags : domogik
Click on **Create**.
The build will be automatically started for the branch **master**. It may fail with the reason: ::
Conf file not found.
This is normal as the master branch contains no documentation (and no plugin code) if you are working on the first release of your plugin!
You will now need to activate the **develop** branch for your RTD plugin project.
Generate documentation for the develop branch
=============================================
From the dashboard, for your plugin project, click on the **Admin** button. In the menu, go in **Versions**.
Set the **develop** version as **Active**. Uncheck the **Active** checkbox for the **latest** version and click on **Submit**.
You are now on the **Overview** page for your plugin project. The only version available is **develop**. You can click on **Build** to start the build of the documentation for the **develop** branch.
In the **Builds** menu for your project, you can check if the build was successful or not. If not, you can click on the status to get the error details.
You can now see the built documentation at http://domogik-plugin-myplugin.readthedocs.org/en/develop/ (adapt *myplugin* to your plugin name)
Notice that the **View Docs** button will send you to the **latest** version of your plugin documentation, which does not exists yet! This version will exists when your plugin will be stable and so, when you will have merge the **develop** branch in the **master** branch.
Set the hook to build the doc for each commit pushed
====================================================
In your github project, you can set a hook to launch the documentation build on RTD for each commit pushed.
Go on your Github project url. For example https://github.com/mygithublogin/domogik-plugin-myplugin
* Go in the **Settings** menu, then in **Webhooks and services**.
* In the **Services** part, click on **Add service** and choose **ReadTheDocs**.
* The ReadTheDocs service configuration page will be displayed. Check that **Active** is set and click on **Add service**.
Now, just do a documentation update, commit it and push it. You should see the doc updated a few minutes later.
Versions management
===================
..todo ::
Continue :)
* version management
i18n
====
..todo ::
TODO !
Read the doc :)
===============
Your documentation is available at **http://domogik-plugin-<plugin name>.readthedocs.org/en/<branch name>/**. Example : http://domogik-plugin-teleinfo.readthedocs.org/en/develop/