Mercurial > libervia-website

annotate tasks/task_generate_doc.py @ 35:347d32030451 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
presentation (docker): add info on how to connect
author Goffi <goffi@goffi.org>
date Tue, 12 Dec 2023 17:01:20 +0100
parents e7c7327f9f25
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6
9ce41ef66dfa python 3 port
Goffi <goffi@goffi.org>
parents: 0
diff changeset
1 #!/ur/bin/env python3
0
09d66acc7c73 initial commit, website first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
2
20
a24d362796be use python module to run sphinx:
Goffi <goffi@goffi.org>
parents: 7
diff changeset
3 import sys
0
09d66acc7c73 initial commit, website first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
4 import os.path
28
e7c7327f9f25 refactoring: fix imports and names in doc following modules hierarchy refactoring
Goffi <goffi@goffi.org>
parents: 24
diff changeset
5 from libervia.backend.core.i18n import _
e7c7327f9f25 refactoring: fix imports and names in doc following modules hierarchy refactoring
Goffi <goffi@goffi.org>
parents: 24
diff changeset
6 from libervia.backend.core.log import getLogger
e7c7327f9f25 refactoring: fix imports and names in doc following modules hierarchy refactoring
Goffi <goffi@goffi.org>
parents: 24
diff changeset
7 from libervia.backend.tools.common import regex
e7c7327f9f25 refactoring: fix imports and names in doc following modules hierarchy refactoring
Goffi <goffi@goffi.org>
parents: 24
diff changeset
8 from libervia.web.server.tasks import task
0
09d66acc7c73 initial commit, website first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
9
09d66acc7c73 initial commit, website first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
10
7
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
11 log = getLogger(__name__)
0
09d66acc7c73 initial commit, website first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
12
09d66acc7c73 initial commit, website first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
13
7
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
14 class Task(task.Task):
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
15 DOC_DIRS_DEFAULT = ('doc', 'docs')
0
09d66acc7c73 initial commit, website first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
16
7
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
17 def prepare(self):
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
18 to_watch = set()
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
19 # root documentation
22
5fd933e238bb massive refactoring from camelCase -> snake_case. See backend commit log for more details
Goffi <goffi@goffi.org>
parents: 20
diff changeset
20 self.doc_path = self.config_get("doc_path")
7
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
21 if self.doc_path is not None:
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
22 to_watch.add(self.doc_path)
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
23 # sub docs will be generated before the root documentation
22
5fd933e238bb massive refactoring from camelCase -> snake_case. See backend commit log for more details
Goffi <goffi@goffi.org>
parents: 20
diff changeset
24 self.sub_docs = self.config_get("sub_docs_dict", value_type="path")
7
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
25 if self.sub_docs is not None:
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
26 for d in list(self.sub_docs.values()):
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
27 to_watch.add(d)
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
28 self.WATCH_DIRS = list(to_watch)
0
09d66acc7c73 initial commit, website first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
29
7
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
30 async def start(self):
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
31 if self.doc_path is None:
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
32 # we check if there is documentation inside the site
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
33 for dirname in self.DOC_DIRS_DEFAULT:
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
34 path = os.path.join(self.site_path, dirname)
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
35 conf_file = os.path.join(path, 'conf.py')
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
36 if os.path.isdir(path) and os.path.exists(conf_file):
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
37 self.doc_path = path
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
38 break
0
09d66acc7c73 initial commit, website first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
39
7
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
40 if self.doc_path is None and self.sub_docs is None:
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
41 log.info("No documentation found for {site_name}, skipping".format(
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
42 site_name = self.site_name))
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
43 return
0
09d66acc7c73 initial commit, website first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
44
7
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
45 # we first generate the sub documentations
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
46 for name, sub_doc_path in list(self.sub_docs.items()):
22
5fd933e238bb massive refactoring from camelCase -> snake_case. See backend commit log for more details
Goffi <goffi@goffi.org>
parents: 20
diff changeset
47 sub_dir = regex.path_escape(name or '')
7
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
48 build_path = os.path.join(self.build_path, 'doc', sub_dir)
24
e4002775d750 doc: log path of generated doc
Goffi <goffi@goffi.org>
parents: 22
diff changeset
49 log.info(f"generating doc for {sub_doc_path}")
20
a24d362796be use python module to run sphinx:
Goffi <goffi@goffi.org>
parents: 7
diff changeset
50 await self.runCommand(
a24d362796be use python module to run sphinx:
Goffi <goffi@goffi.org>
parents: 7
diff changeset
51 sys.executable, "-m", "sphinx", sub_doc_path, build_path,
a24d362796be use python module to run sphinx:
Goffi <goffi@goffi.org>
parents: 7
diff changeset
52 )
0
09d66acc7c73 initial commit, website first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
53
7
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
54 # then the root one
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
55 if self.doc_path is not None:
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
56 build_path = os.path.join(self.build_path, 'doc')
24
e4002775d750 doc: log path of generated doc
Goffi <goffi@goffi.org>
parents: 22
diff changeset
57 log.info(f"generating doc for {self.doc_path}")
20
a24d362796be use python module to run sphinx:
Goffi <goffi@goffi.org>
parents: 7
diff changeset
58 await self.runCommand(
a24d362796be use python module to run sphinx:
Goffi <goffi@goffi.org>
parents: 7
diff changeset
59 sys.executable, "-m", "sphinx", self.doc_path, build_path,
a24d362796be use python module to run sphinx:
Goffi <goffi@goffi.org>
parents: 7
diff changeset
60 )
7
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
61
b5fc67c97c50 tasks: updated tasks following changes in Libervia
Goffi <goffi@goffi.org>
parents: 6
diff changeset
62 log.info(_("documentation has been generated"))