Skip to content

Commit f7e6ac7

Browse files
kylefkylef
committed
Introduce sphinx documentation
1 parent b6b80f7 commit f7e6ac7

File tree

12 files changed

+890
-2
lines changed

12 files changed

+890
-2
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,6 @@
22
/versions/
33
/version
44
/bats/
5+
6+
/docs/_build/
7+
/docs/_build_html/

‎README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ swiftenv allows you to easily install, and switch between multiple versions of S
66

77
This project was heavily inspired by [pyenv](https://github.com/yyuu/pyenv).
88

9-
![swiftenv screenshot](share/swiftenv.png)
9+
![swiftenv screenshot](docs/_static/swiftenv.png)
1010

1111
swiftenv allows you to:
1212

@@ -128,7 +128,7 @@ all of the dependencies mention on
128128
requirements](https://github.com/apple/swift#system-requirements). It is
129129
important to note that the Swift Package Manager will not be installed with
130130
`2.2-dev` as Swift Package Manager is still in early development and it won't
131-
be included in 2.2, however it is available in the binary snapshots.
131+
be included in 2.2, however it is available in the development binary snapshots.
132132
133133
```shell
134134
$ swiftenv install 2.2-SNAPSHOT-2016-01-11-a

‎docs/Makefile

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# Makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
PAPER =
8+
BUILDDIR = _build
9+
10+
# User-friendly check for sphinx-build
11+
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
12+
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
13+
endif
14+
15+
# Internal variables.
16+
PAPEROPT_a4 = -D latex_paper_size=a4
17+
PAPEROPT_letter = -D latex_paper_size=letter
18+
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
19+
# the i18n builder cannot share the environment and doctrees with the others
20+
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
21+
22+
.PHONY: help
23+
help:
24+
@echo "Please use \`make <target>' where <target> is one of"
25+
@echo " html to make standalone HTML files"
26+
@echo " dirhtml to make HTML files named index.html in directories"
27+
@echo " singlehtml to make a single large HTML file"
28+
@echo " pickle to make pickle files"
29+
@echo " json to make JSON files"
30+
@echo " htmlhelp to make HTML files and a HTML help project"
31+
@echo " qthelp to make HTML files and a qthelp project"
32+
@echo " applehelp to make an Apple Help Book"
33+
@echo " devhelp to make HTML files and a Devhelp project"
34+
@echo " epub to make an epub"
35+
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
36+
@echo " latexpdf to make LaTeX files and run them through pdflatex"
37+
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
38+
@echo " text to make text files"
39+
@echo " man to make manual pages"
40+
@echo " texinfo to make Texinfo files"
41+
@echo " info to make Texinfo files and run them through makeinfo"
42+
@echo " gettext to make PO message catalogs"
43+
@echo " changes to make an overview of all changed/added/deprecated items"
44+
@echo " xml to make Docutils-native XML files"
45+
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
46+
@echo " linkcheck to check all external links for integrity"
47+
48+
.PHONY: clean
49+
clean:
50+
rm -rf $(BUILDDIR)/*
51+
52+
.PHONY: html
53+
html:
54+
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
55+
@echo
56+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
57+
58+
.PHONY: dirhtml
59+
dirhtml:
60+
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
61+
@echo
62+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
63+
64+
.PHONY: singlehtml
65+
singlehtml:
66+
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
67+
@echo
68+
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
69+
70+
.PHONY: pickle
71+
pickle:
72+
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
73+
@echo
74+
@echo "Build finished; now you can process the pickle files."
75+
76+
.PHONY: json
77+
json:
78+
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
79+
@echo
80+
@echo "Build finished; now you can process the JSON files."
81+
82+
.PHONY: htmlhelp
83+
htmlhelp:
84+
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
85+
@echo
86+
@echo "Build finished; now you can run HTML Help Workshop with the" \
87+
".hhp project file in $(BUILDDIR)/htmlhelp."
88+
89+
.PHONY: qthelp
90+
qthelp:
91+
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
92+
@echo
93+
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
94+
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
95+
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/swiftenv.qhcp"
96+
@echo "To view the help file:"
97+
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/swiftenv.qhc"
98+
99+
.PHONY: applehelp
100+
applehelp:
101+
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
102+
@echo
103+
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
104+
@echo "N.B. You won't be able to view it unless you put it in" \
105+
"~/Library/Documentation/Help or install it in your application" \
106+
"bundle."
107+
108+
.PHONY: devhelp
109+
devhelp:
110+
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
111+
@echo
112+
@echo "Build finished."
113+
@echo "To view the help file:"
114+
@echo "# mkdir -p $$HOME/.local/share/devhelp/swiftenv"
115+
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/swiftenv"
116+
@echo "# devhelp"
117+
118+
.PHONY: epub
119+
epub:
120+
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
121+
@echo
122+
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
123+
124+
.PHONY: latex
125+
latex:
126+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
127+
@echo
128+
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
129+
@echo "Run \`make' in that directory to run these through (pdf)latex" \
130+
"(use \`make latexpdf' here to do that automatically)."
131+
132+
.PHONY: latexpdf
133+
latexpdf:
134+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
135+
@echo "Running LaTeX files through pdflatex..."
136+
$(MAKE) -C $(BUILDDIR)/latex all-pdf
137+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
138+
139+
.PHONY: latexpdfja
140+
latexpdfja:
141+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
142+
@echo "Running LaTeX files through platex and dvipdfmx..."
143+
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
144+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
145+
146+
.PHONY: text
147+
text:
148+
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
149+
@echo
150+
@echo "Build finished. The text files are in $(BUILDDIR)/text."
151+
152+
.PHONY: man
153+
man:
154+
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
155+
@echo
156+
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
157+
158+
.PHONY: texinfo
159+
texinfo:
160+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
161+
@echo
162+
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
163+
@echo "Run \`make' in that directory to run these through makeinfo" \
164+
"(use \`make info' here to do that automatically)."
165+
166+
.PHONY: info
167+
info:
168+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
169+
@echo "Running Texinfo files through makeinfo..."
170+
make -C $(BUILDDIR)/texinfo info
171+
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
172+
173+
.PHONY: gettext
174+
gettext:
175+
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
176+
@echo
177+
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
178+
179+
.PHONY: changes
180+
changes:
181+
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
182+
@echo
183+
@echo "The overview file is in $(BUILDDIR)/changes."
184+
185+
.PHONY: linkcheck
186+
linkcheck:
187+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
188+
@echo
189+
@echo "Link check complete; look for any errors in the above output " \
190+
"or in $(BUILDDIR)/linkcheck/output.txt."
191+
192+
.PHONY: xml
193+
xml:
194+
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
195+
@echo
196+
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
197+
198+
.PHONY: pseudoxml
199+
pseudoxml:
200+
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
201+
@echo
202+
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

‎share/swiftenv.png renamed to ‎docs/_static/swiftenv.png

File renamed without changes.

‎docs/_templates/sidebar_intro.html

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<h1><a href="/">swiftenv</a></h1>
2+
3+
<p>
4+
<iframe
5+
src="http://ghbtns.com/github-btn.html?user=kylef&repo=swiftenv&type=watch&count=true&size=large"
6+
allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px">
7+
</iframe>
8+
</p>
9+
10+
<p>swiftenv allows you to easily install, and switch between multiple versions of Swift.</p>
11+
12+
<div class="social">
13+
<p>
14+
<iframe
15+
src="http://ghbtns.com/github-btn.html?user=kylef&type=follow&count=false"
16+
allowtransparency="true" frameborder="0" scrolling="0" width="200" height="20">
17+
</iframe>
18+
</p>
19+
20+
<p>
21+
<a href="https://twitter.com/kylefuller" class="twitter-follow-button" data-show-count="false">Follow @kylefuller</a> <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
22+
</p>
23+
</div>
24+
25+
<h3>Other Projects</h3>
26+
27+
<p>More <a href="https://fuller.li/">Kyle Fuller</a> projects:</p>
28+
<ul>
29+
<li><a href="https://github.com/kylef/Commander">Commander</a></li>
30+
<li><a href="https://github.com/kylef/Curassow">Curassow</a></li>
31+
<li><a href="https://github.com/kylef/Spectre">Spectre</a></li>
32+
<li><a href="https://github.com/kylef/heroku-buildpack-swift">Heroku Swift buildpack</a></li>
33+
</ul>

‎docs/commands.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Command Reference
2+
3+
## `version`
4+
5+
Displays the current active Swift version and why it was chosen.
6+
7+
```shell
8+
$ swiftenv version
9+
2.2-SNAPSHOT-2015-12-10-a (set by /home/kyle/.swiftenv/version)
10+
```
11+
12+
## `versions`
13+
14+
Lists all installed Swift versions, showing an asterisk next to the currently
15+
active version.
16+
17+
```shell
18+
$ swiftenv versions
19+
2.2-SNAPSHOT-2015-12-01-b
20+
* 2.2-SNAPSHOT-2015-12-10-a (set by /home/kyle/.swiftenv/version)
21+
```
22+
23+
## `global`
24+
25+
Sets the global version of Swift to be used by writing to the
26+
`~/.swiftenv/version` file. This version can be overridden by
27+
application-specific `.swift-version` file, or by setting the `SWIFT_VERSION`
28+
environment variable.
29+
30+
```shell
31+
$ swiftenv global 2.2-SNAPSHOT-2015-12-10-a
32+
$ swiftenv global
33+
2.2-SNAPSHOT-2015-12-10-a
34+
```
35+
36+
## `local`
37+
38+
Sets the local application-specific Swift version by writing the version to a
39+
`.swift-version` file in the current directory. This version overrides the
40+
global version and can also be overridden by th `SWIFT_VERSION` environment
41+
variable.
42+
43+
```shell
44+
$ swiftenv local 2.2-SNAPSHOT-2015-12-10-a
45+
$ swiftenv local
46+
2.2-SNAPSHOT-2015-12-10-a
47+
```
48+
49+
## `install`
50+
51+
Installs a version of Swift. This supports any binary release provides by
52+
Apple. For example, a 2.2 snapshots such as `2.2-SNAPSHOT-2016-01-11-a`.
53+
54+
You may also specify `2.2-dev` to build Swift from source, this will require
55+
all of the dependencies mention on
56+
[Swift system
57+
requirements](https://github.com/apple/swift#system-requirements). It is
58+
important to note that the Swift Package Manager will not be installed with
59+
`2.2-dev` as Swift Package Manager is still in early development and it won't
60+
be included in 2.2, however it is available in the development binary snapshots.
61+
62+
```shell
63+
$ swiftenv install 2.2-SNAPSHOT-2016-01-11-a
64+
Downloading 2.2-SNAPSHOT-2016-01-11-a from https://swift.org/builds/ubuntu1510/swift-2.2-SNAPSHOT-2016-01-11-a/swift-2.2-SNAPSHOT-2016-01-11-a-ubuntu15.10.tar.gz
65+
```
66+
67+
You may also manually install Swift and make it accessible to swiftenv. Custom
68+
Swift installations can either be placed in a directory using the correct
69+
version number at `~/.swiftenv/versions/VERSION`, or can be symbolic
70+
linked into the version directory.
71+
72+
It is expected that all dependencies are already installed for running Swift,
73+
please consult the [Swift website](https://swift.org/download/) for more
74+
information.
75+
76+
**NOTE**: *After manually installing a version of Swift, it's recommended that
77+
you run `swiftenv rehash` to update the shims.*
78+
79+
## `uninstall`
80+
81+
Uninstalls a specific Swift version.
82+
83+
```shell
84+
$ swiftenv uninstall 2.2-SNAPSHOT-2015-12-10-a
85+
```
86+
87+
## `rehash`
88+
89+
Installs shims for the Swift binaries. This command should be ran after you
90+
manually install new versions of Swift.
91+
92+
```shell
93+
$ swiftenv rehash
94+
```
95+
96+
## `which`
97+
98+
Displays the full path to the executable that would be invoked for the selected
99+
version for the given command.
100+
101+
```shell
102+
$ swiftenv which swift
103+
/home/kyle/.swiftenv/versions/swift-2.2-SNAPSHOT-2015-12-10-a/usr/bin/swift
104+
105+
$ swiftenv which lldb
106+
/home/kyle/.swiftenv/versions/swift-2.2-SNAPSHOT-2015-12-10-a/usr/bin/lldb
107+
```

0 commit comments

Comments
 (0)