@@ -15,6 +15,122 @@ These are relevant documents related to the content in this repository:
1515See [ CONTRIBUTING.md] ( CONTRIBUTING.md ) for how to go about contributing to
1616this array API standard.
1717
18+
19+ ## Building docs locally
20+
21+ The spec website is comprised of multiple Sphinx docs (one for each spec version),
22+ all of which exist in ` spec/ ` and rely on the modules found in ` src/ ` (most
23+ notably ` array_api_stubs ` ). To install these modules and the additional
24+ dependencies of the Sphinx docs, you can use
25+
26+ ``` sh
27+ $ pip install -e .[doc] # ensure you install the dependencies extra "doc"
28+ ```
29+
30+ To build specific versions of the spec, run ` sphinx-build ` on the respective
31+ folder in ` spec/ ` , e.g.
32+
33+ ``` sh
34+ $ sphinx-build spec/draft/ _site/draft/
35+ ```
36+
37+ To build the whole website, which includes every version of
38+ the spec, you can utilize the ` make ` commands defined in ` spec/Makefile ` ; e.g.,
39+
40+ ``` sh
41+ $ make
42+ $ ls _site/
43+ 2021.12/ draft/ index.html latest/ versions.json
44+ ```
45+
46+
47+ ## Making a spec release
48+
49+ The Sphinx doc at ` spec/draft/ ` should be where the in-development spec resides,
50+ with ` src/array_api_stubs/_draft/ ` containing its respective stubs. A spec
51+ release should involve:
52+
53+ * Renaming ` src/array_api_stubs/_draft/ ` to ` src/array_api_stubs/_YYYY_MM `
54+ * Renaming ` spec/draft/ ` to ` spec/YYYY.MM `
55+ * Updating ` spec/YYYY.MM/conf.py `
56+
57+ ``` diff
58+ ...
59+ - from array_api_stubs import _draft as stubs_mod
60+ + from array_api_stubs import _YYYY_MM as stubs_mod
61+ ...
62+ - release = "DRAFT"
63+ + release = "YYYY.MM"
64+ ...
65+ ```
66+
67+ * Updating ` spec/_ghpages/versions.json `
68+
69+ ``` diff
70+ {
71+ + "YYYY.MM": "YYYY.MM",
72+ ...
73+ ```
74+
75+ * Updating ` Makefile `
76+
77+ ``` diff
78+ ...
79+ -sphinx-build "$(SOURCEDIR)/PREVIOUS.VER" "$(BUILDDIR)/PREVIOUS.VER" $(SPHINXOPTS)
80+ + -sphinx-build "$(SOURCEDIR)/YYYY.MM" "$(BUILDDIR)/YYYY.MM" $(SPHINXOPTS)
81+ - -cp -r "$(BUILDDIR)/PREVIOUS.VER" "$(BUILDDIR)/latest"
82+ + -cp -r "$(BUILDDIR)/YYYY.MM" "$(BUILDDIR)/latest"
83+ ...
84+ ```
85+
86+ These changes should be committed and tagged. The next draft should then be
87+ created. To preserve git history for both the new release and the next draft:
88+
89+ 1 . Create and checkout to a new temporary branch.
90+
91+ ``` sh
92+ $ git checkout -b tmp
93+ ```
94+
95+ 2 . Make an empty commit. <sup >This is required so merging the temporary branch
96+ (4.) is not automatic.</sup >
97+
98+ ``` sh
99+ $ git commit --allow-empty -m " Empty commit for draft at YYYY.MM "
100+ ```
101+
102+ 3 . Checkout back to the branch you are making a spec release in.
103+
104+ ``` sh
105+ $ git checkout YYYY.MM-release
106+ ```
107+
108+ 4 . Merge the temporary branch, specifying no commit and no fast-forwarding.
109+
110+ ``` sh
111+ $ git merge --no-commit --no-ff tmp
112+ Automatic merge went well; stopped before committing as requested
113+ ```
114+
115+ 5 . Checkout the ` spec/draft/ ` files from the temporary branch.
116+
117+ ``` sh
118+ $ git checkout tmp -- spec/draft/
119+ ```
120+
121+ 6 . Commit your changes.
122+
123+ ``` sh
124+ $ git commit -m " Copy YYYY.MM as draft with preserved git history"
125+ ```
126+
127+ You can run ` git blame ` on both ` spec/YYYY.MM ` and ` spec/draft ` files to verify
128+ we've preserved history. See this [ StackOverflow question] ( https://stackoverflow.com/q/74365771/5193926 )
129+ for more background on the approach we use.
130+
131+ <!-- TODO: write a script to automate/standardise spec releases -->
132+
133+
18134## Contributors ✨
19135
20136Thanks goes to these wonderful people ([ emoji key] ( https://allcontributors.org/docs/en/emoji-key ) ):
0 commit comments