Coverage for /home/runner/work/coxbuild/coxbuild/src/coxbuild/extensions/python/docs.py: 0%

1from pathlib import Path 

2 

3from coxbuild import get_working_directory 

4from coxbuild.schema import depend, group, precond, run, task 

5 

6from .. import ProjectSettings, withProject 

7from . import grouped 

8from .package import hasPackages, upgradePackages 

9 

10subgrouped = group("docs") 

11 

12 

13@grouped 

14@subgrouped 

15@precond(lambda: not hasPackages({"Sphinx": "*"})) 

16@task 

17def restore(): 

18 """Restore Python docs tools.""" 

19 upgradePackages("Sphinx") 

20 

21 

22@grouped 

23@subgrouped 

24@withProject 

25@depend(restore) 

26@task 

27def sphinx_init(docs: Path | None = None, *, project: ProjectSettings): 

28 """Initialize sphinx to generate API documents.""" 

29 run(["sphinx-quickstart"], cwd=docs or project.docs) 

30 

31 

32@grouped 

33@subgrouped 

34@withProject 

35@depend(restore) 

36@task 

37def sphinx_api(src: Path | None = None, docs: Path | None = None, *, project: ProjectSettings): 

38 """Use sphinx to generate API documents.""" 

39 run(["sphinx-apidoc", "-o", "source", str(src or project.src)], 

40 cwd=docs or project.docs) 

41 

42 

43@grouped 

44@subgrouped 

45@depend(sphinx_api) 

46@withProject 

47@task 

48def sphinx_html(docs: Path | None = None, *, project: ProjectSettings): 

49 """Use sphinx to generate API documents in HTML.""" 

50 run(["sphinx-build", "-b", "html", ".", "_build"], 

51 cwd=docs or project.docs) 

52 

53 

54@grouped 

55@subgrouped 

56@depend(sphinx_html) 

57@task 

58def apidoc(): 

59 """Generate API documents to {projectSettings.docs}/_build.""" 

60 pass