Skip to content

Commit 0a05369

Browse files
ggnaegiraman-m
ggnaegi
and
raman-m
authored
#1731 Read the Docs configuration file v2 (#1733)
* fixing the documentation, using Release/20.0 as base branch * using latest conf.py, created with sphinx-quickstart, fixing the warnings during documentation generation * Update .readthedocs.yaml * switching to threemammals.org for copyright * adding requirements file, updating readthedocs.yaml, adding formats pdf / epub and config for requirements file * fixing code block in websockets.rst * ok, now it should be fine... * Update kubernetes.rst: Review and fix markup code * Update websockets.rst: Review and fix markup * Update conf.py: Update release, author and copyright --------- Co-authored-by: Raman Maksimchuk <[email protected]>
1 parent 637fde8 commit 0a05369

15 files changed

+157
-1182
lines changed

‎.readthedocs.yaml

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# .readthedocs.yaml
2+
# Read the Docs configuration file
3+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4+
5+
# Required
6+
version: 2
7+
8+
# Set the OS, Python version and other tools you might need
9+
build:
10+
os: ubuntu-22.04
11+
tools:
12+
python: "3.11"
13+
# You can also specify other tool versions:
14+
# nodejs: "19"
15+
# rust: "1.64"
16+
# golang: "1.19"
17+
18+
# Build documentation in the "docs/" directory with Sphinx
19+
sphinx:
20+
configuration: docs/conf.py
21+
22+
# Optionally build your docs in additional formats such as PDF and ePub
23+
formats:
24+
- pdf
25+
- epub
26+
27+
# Optional but recommended, declare the Python requirements required to build your documentation
28+
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
29+
python:
30+
install:
31+
- requirements: docs/requirements.txt

‎Ocelot.sln

+1
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
1010
.dockerignore = .dockerignore
1111
.editorconfig = .editorconfig
1212
.gitignore = .gitignore
13+
.readthedocs.yaml = .readthedocs.yaml
1314
build.cake = build.cake
1415
build.ps1 = build.ps1
1516
codeanalysis.ruleset = codeanalysis.ruleset

‎docs/Makefile

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

‎docs/autobuild.bat

-1
This file was deleted.

‎docs/building/releaseprocess.rst

+1
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Ocelot uses the following process to accept work into the NuGet packages.
1616
- Have I covered all my changes with tests at unit and acceptance level?
1717
- Have I updated any documentation that my changes may have affected?
1818
- Does my feature make sense, have I checked all of Ocelot's other features to make sure it doesn't already exist?
19+
1920
In order for a PR to be merged the following must have occured.
2021
- All new code is covered by unit tests.
2122
- All new code has at least 1 acceptance test covering the happy path.

0 commit comments

Comments
 (0)