Skip to content

Commit 5d1d05d

Browse files
AwesomeTornadoAwesomeTornado
authored
Add Version Switching (#160)
1 parent a845491 commit 5d1d05d

10 files changed

Lines changed: 147 additions & 24 deletions

File tree

‎Makefile‎

Lines changed: 46 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,60 @@
1-
# Minimal makefile for Sphinx documentation
1+
# Makefile for Sphinx documentation
22
#
33

44
# You can set these variables from the command line, and also
55
# from the environment for the first two.
66
SPHINXOPTS ?=
7-
SPHINXBUILD ?= sphinx-build
7+
SPHINXBUILD ?= sphinx-multiversion
88
SOURCEDIR = source
99
BUILDDIR = build
10+
UNAME = "Windows_NT"
11+
ifeq ($(OS),Windows_NT)
12+
UNAME_AVAIL = "false"
13+
else
14+
UNAME_AVAIL = "true"
15+
endif
16+
17+
ifeq ($(UNAME_AVAIL), "true")
18+
UNAME = $(shell uname -s)
19+
endif
1020

1121
# Put it first so that "make" without argument is like "make help".
1222
help:
13-
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
23+
@$(SPHINXBUILD) --help
1424

1525
.PHONY: help Makefile
1626

17-
# Catch-all target: route all unknown targets to Sphinx using the new
18-
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
27+
# Catch-all target: route all unknown targets to Sphinx
28+
# $(O) is meant as a shortcut for $(SPHINXOPTS).
1929
%: Makefile
20-
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
30+
ifeq ($(UNAME_AVAIL), "true")
31+
ifeq ($(UNAME), Darwin)
32+
#We are on OSX
33+
mkdir -p tmptmp
34+
TMPDIR=$(CURDIR)/tmptmp $(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0)
35+
rm -r tmptmp
36+
cp ./index.html "$(BUILDDIR)/index.html"
37+
else
38+
#We are on Linux
39+
@$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0)
40+
cp ./index.html "$(BUILDDIR)/index.html"
41+
endif
42+
else
43+
#We are on Windows_NT
44+
@$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0)
45+
copy .\index.html "$(BUILDDIR)\index.html"
46+
endif
47+
48+
49+
local:
50+
sphinx-build "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0)
51+
52+
# We are no longer using make functionality of sphinx-build
53+
# because sphinx-multiverison does not support it
54+
# therefore we must define make clean ourselves.
55+
clean:
56+
ifeq ($(OS),Windows_NT)
57+
del /s "$(BUILDDIR)"
58+
else
59+
rm -r "$(BUILDDIR)/"*
60+
endif

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,9 @@ pip install -r requirements.txt
4545

4646
```
4747
make clean
48-
make html
48+
make local
4949
```
5050

51-
3. Browse local docs in your browser by opening: `build/html/index.html`
51+
3. Browse local docs in your browser by opening: `build/index.html`
5252

5353
See [this discussion thread](https://github.com/Severson-Group/docs.amdc.dev/discussions/56) for more information on local development.

‎index.html‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
<head>
2+
<meta http-equiv='refresh' content='0; URL=https://docs.amdc.dev/main'>
3+
</head>

‎make.bat‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,31 +5,39 @@ pushd %~dp0
55
REM Command file for Sphinx documentation
66

77
if "%SPHINXBUILD%" == "" (
8-
set SPHINXBUILD=sphinx-build
8+
set SPHINXBUILD=sphinx-multiversion
99
)
1010
set SOURCEDIR=source
1111
set BUILDDIR=build
1212

1313
if "%1" == "" goto help
14+
if "%1" == "clean" goto clean
1415

1516
%SPHINXBUILD% >NUL 2>NUL
1617
if errorlevel 9009 (
1718
echo.
18-
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19-
echo.installed, then set the SPHINXBUILD environment variable to point
20-
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21-
echo.may add the Sphinx directory to PATH.
19+
echo.The 'sphinx-multiversion' command was not found. Make sure you have Sphinx
20+
echo.and sphinx-multiversion installed, then set the SPHINXBUILD environment
21+
echo.variable to point to the full path of the 'sphinx-build' executable.
22+
echo.Alternatively you may add the Sphinx directory to PATH.
2223
echo.
2324
echo.If you don't have Sphinx installed, grab it from
2425
echo.https://www.sphinx-doc.org/
26+
echo.
27+
echo.Sphinx-Multiversion can be installed with pip
28+
echo.pip install sphinx-multiversion
2529
exit /b 1
2630
)
2731

28-
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
32+
%SPHINXBUILD% %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
goto end
34+
35+
:clean
36+
del /s "$(BUILDDIR)"
2937
goto end
3038

3139
:help
32-
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
40+
%SPHINXBUILD% --help
3341

3442
:end
3543
popd

‎requirements.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@ sphinx>=6.0,<7
22
furo>=2023.05
33
myst_parser>=2.0
44
sphinx_design>=0.4.1
5-
sphinx-last-updated-by-git>=0.3
65
sphinx-copybutton>=0.4
76
sphinx-sitemap>=2.2
87
pygments>=2.10
98
matplotlib>=3.7
109
zipp>=3.1
11-
docutils<0.20,>=0.18.1
10+
docutils<0.20,>=0.18.1
11+
sphinx-multiversion>=0.2.4

‎source/_templates/versioning.html‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{% if versions %}
2+
<h4>{{ _('Versions') }}</h4>
3+
<ul style="display:flex; flex-direction:column-reverse">
4+
{%- for item in versions.tags %}
5+
<li style="flex: 0 0 auto;"><a href="{{ item.url }}">{{ item.name }}</a></li>
6+
{%- endfor %}
7+
<li><a href="{{ versions.branches[0].url }}">Latest</a></li>
8+
</ul>
9+
{% endif %}

‎source/conf.py‎

Lines changed: 28 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,10 +31,10 @@
3131
extensions = [
3232
'myst_parser',
3333
'sphinx_design',
34-
'sphinx_last_updated_by_git',
3534
'sphinx_copybutton',
3635
'sphinx_sitemap',
37-
'matplotlib.sphinxext.plot_directive'
36+
'matplotlib.sphinxext.plot_directive',
37+
'sphinx_multiversion'
3838
]
3939

4040
myst_enable_extensions = [
@@ -77,6 +77,30 @@
7777

7878
html_extra_path = ['robots.txt']
7979

80+
81+
html_sidebars = {
82+
"**": [
83+
"sidebar/brand.html",
84+
"sidebar/search.html",
85+
"sidebar/scroll-start.html",
86+
"sidebar/navigation.html",
87+
"versioning.html",
88+
"sidebar/scroll-end.html",
89+
]
90+
}
91+
92+
93+
# Sphinx-multiversion configuration
94+
# Whitelist pattern for remotes (set to None to use local branches only)
95+
smv_remote_whitelist = r'^v\d\..*|main$'
96+
97+
# Whitelist pattern for tags
98+
smv_tag_whitelist = r'^v\d\..*$'
99+
100+
# Whitelist pattern for branches
101+
smv_branch_whitelist = r'^main$'
102+
103+
80104
# Add any paths that contain custom static files (such as style sheets) here,
81105
# relative to this directory. They are copied after the builtin static files,
82106
# so a file named "default.css" will overwrite the builtin "default.css".
@@ -89,8 +113,9 @@
89113
]
90114

91115

116+
92117
# Matplotlib options
93118
plot_html_show_source_link = False
94119
plot_html_show_formats = False
95120
plot_formats = ['svg']
96-
plot_rcparams = {'font.size' : 12}
121+
plot_rcparams = {'font.size' : 12}

‎source/contribution/index.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Developers
2+
3+
This page serves as a guide to help people developing the documentation.
4+
5+
## Versioning
6+
7+
We use Sphinx-Multiversion to allow users to view historic revisions of our documentation.
8+
9+
### Sphinx Multiversion Overview
10+
11+
Sphinx has been configured to search for tags starting with `v#.` and add them to the version switcher at the bottom of the page. The version switcher has also been configured to put the branch named `main` at the very top, labled as `latest`.
12+
During the build process sphinx will go to the commits that the various tags are pointing to, build them, and put the results in seperate folders. Each folder is accessable online as a part of the url when visiting the docs. For example, `docs.amdc.dev/v1.0/index.html` points to the `v1.0` folder, while `docs.amdc.dev/v2.0/index.html` points to the `v2.0` folder.
13+
14+
### Organization of Tags
15+
16+
Each tag is a snapshot of the docs at one point in time, representing the most up to date documentation for the [AMDC-Firmware](https://github.com/Severson-Group/AMDC-Firmware) revision it is tagged as.
17+
Please note that the latest firmware release does not have its own tag! Instead, it is assumed that `main` contains the most up to date documentation for the current firmware revision.
18+
19+
When releasing a new firmware version, the latest commit on `main` should be tagged as the firmware revision it was written for (the version prior to the one currently being released). This will give it an entry in the version selector. Now, any documentation for the new firmware release can now be merged in without removing access to previous documentation. The main branch remains the most up to date documentation, and now targets the new firmware version that was just released.
20+
21+
```{NOTE}
22+
This project's policy is to only tag major and minor [AMDC-Firmware](https://github.com/Severson-Group/AMDC-Firmware) versions. Bug fix releases do not get their own tag in the docs. The tagging procedure is described in the [firmware release procedure](minor-or-major-release).
23+
```
24+
25+
## Makefiles and Build scripts
26+
27+
The Makefile is the most up to date method of building the documentation, and can be used by running `make clean` or `make html`.
28+
```{CAUTION}
29+
Sphinx-Multiversion does **not** take local changes into account when building the docs! Changes you want to view must be commited when testing the version switcher.
30+
```
31+
For building the documentation locally, `make local` can be used to only build the files on your computer, instead of building the entire version tree. This allows you to test changes without making commits.

‎source/firmware/development/index.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -71,13 +71,15 @@ Occasionally, a bug might need to be fixed in a previous release branch, but doe
7171
In this case, do not change `develop` -- simply fix the bug where it needs to be fixed.
7272
This is depicted in the above diagram as the `hotfix1` branch.
7373

74+
(minor-or-major-release)=
7475
#### Minor or Major
7576

7677
For a new minor or major release, a new release branch needs to be created.
7778

78-
1. Create a new release branch from `develop` and call it `vA.B.x`
79-
2. Update GitHub's default repo branch to be the latest release branch which was just created
80-
3. Update the documentation website to reflect the minor or major (breaking) changes
79+
1. Tag the most recent commit to `main` on [docs.amdc.dev](https://github.com/Severson-Group/docs.amdc.dev) as the ***previous*** firmware release with `vA.B` formatting (see the [Developers guide](../../contribution/index.md))
80+
2. Create a new release branch from `develop` on AMDC-firmware and call it `vA.B.x`
81+
3. Update GitHub's default repo branch to be the latest release branch which was just created
82+
4. Update the documentation website to reflect the minor or major (breaking) changes
8183

8284
### Tag and Release
8385

@@ -87,4 +89,4 @@ Users which checkout the release branch will have access to the code.
8789
To complete the release, git tag(s) need to be created and GitHub release(s) need to be created.
8890

8991
1. Create git tag(s) pointing to the merge commit(s) on the release branch(es). If the new code was only merged to one release branch, only one tag will be created. However, if a bug fix was merged to multiple release branches, then the appropriate version number should be used to tag each merge commit.
90-
2. For each new git tag, create a GitHub Release with the same name as the tag and include a description of the changes per the changelog contents.
92+
2. For each new git tag, create a GitHub Release with the same name as the tag and include a description of the changes per the changelog contents.

‎source/index.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,11 @@ AMDC Platform Documentation
5151
DAC <accessories/dac/index>
5252
accessories/test-board/index
5353

54+
.. toctree::
55+
:hidden:
56+
:caption: Contribution
57+
58+
contribution/index
5459

5560
Welcome to the AMDC Platform documentation.
5661
This is an ever-growing collection of knowledge about the AMDC.

0 commit comments

Comments
 (0)