on master help sign in
docs: generic documentation get templating

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

commitf25da6070e398f17c24b194c8688595050dc473c authorMarkus Heiser <markus.heiser@darmarit.de> dateTue 3 Mar 2020, 16:26 (7 years ago) parent7af991a
3 files changed+162−161
docs/build-templates/searx.rst+159 docs/conf.py+2 utils/searx.sh+1−161
docs/build-templates/searx.rstnew file+159
@@ -0,0 +1,159 @@
1+.. template evaluated by: ./utils/searx.sh docs
2+.. hint: all dollar-names are variables, dollar sign itself is quoted by: \\$
3+
4+.. START distro-packages
5+
6+.. tabs::
7+
8+ .. group-tab:: Ubuntu / debian
9+
10+ .. code-block:: sh
11+
12+ $ sudo -H apt-get install -y \\
13+${debian}
14+
15+ .. group-tab:: Arch Linux
16+
17+ .. code-block:: sh
18+
19+ $ sudo -H pacman -S --noconfirm \\
20+${arch}
21+
22+ .. group-tab:: Fedora / RHEL
23+
24+ .. code-block:: sh
25+
26+ $ sudo -H dnf install -y \\
27+${fedora}
28+
29+.. END distro-packages
30+
31+
32+.. START create user
33+
34+.. tabs::
35+
36+ .. group-tab:: bash
37+
38+ .. code-block:: sh
39+
40+ $ sudo -H useradd --shell /bin/bash --system \\
41+ --home-dir "$SERVICE_HOME" \\
42+ --comment "Privacy-respecting metasearch engine" $SERVICE_USER
43+
44+ $ sudo -H mkdir "$SERVICE_HOME"
45+ $ sudo -H chown -R "$SERVICE_GROUP:$SERVICE_GROUP" "$SERVICE_HOME"
46+
47+.. END create user
48+
49+.. START clone searx
50+
51+.. tabs::
52+
53+ .. group-tab:: bash
54+
55+ .. code-block:: sh
56+
57+ $ sudo -H -u ${SERVICE_USER} -i
58+ (${SERVICE_USER})$ git clone "https://github.com/asciimoo/searx.git" "$SEARX_SRC"
59+
60+.. END clone searx
61+
62+.. START create virtualenv
63+
64+.. tabs::
65+
66+ .. group-tab:: bash
67+
68+ .. code-block:: sh
69+
70+ (${SERVICE_USER})$ python3 -m venv "${SEARX_PYENV}"
71+ (${SERVICE_USER})$ echo ". ${SEARX_PYENV}/bin/activate" >> "$SERVICE_HOME/.profile"
72+
73+.. END create virtualenv
74+
75+.. START manage.sh update_packages
76+
77+.. tabs::
78+
79+ .. group-tab:: bash
80+
81+ .. code-block:: sh
82+
83+ $ sudo -H -u ${SERVICE_USER} -i
84+
85+ (${SERVICE_USER})$ command -v python && python --version
86+ $SEARX_PYENV/bin/python
87+ Python 3.8.1
88+
89+ (${SERVICE_USER})$ cd "$SEARX_SRC"
90+ (${SERVICE_USER})$ ./manage.sh update_packages
91+
92+.. END manage.sh update_packages
93+
94+.. START searx config
95+
96+.. tabs::
97+
98+ .. group-tab:: bash
99+
100+ .. code-block:: sh
101+
102+ $ sudo -H cp "$SEARX_SRC/searx/settings.yml" "${SEARX_SETTINGS_PATH}"
103+ $ sudo -H sed -i -e "s/ultrasecretkey/\\$(openssl rand -hex 16)/g" "$SEARX_SETTINGS_PATH"
104+ $ sudo -H sed -i -e "s/{instance_name}/searx@\\$(uname -n)/g" "$SEARX_SETTINGS_PATH"
105+
106+.. END searx config
107+
108+.. START check searx installation
109+
110+.. tabs::
111+
112+ .. group-tab:: bash
113+
114+ .. code-block:: sh
115+
116+ # enable debug ..
117+ $ sudo -H sed -i -e "s/debug : False/debug : True/g" "$SEARX_SETTINGS_PATH"
118+
119+ # start webapp
120+ $ sudo -H -u ${SERVICE_USER} -i
121+ (${SERVICE_USER})$ cd ${SEARX_SRC}
122+ (${SERVICE_USER})$ export SEARX_SETTINGS_PATH="${SEARX_SETTINGS_PATH}"
123+ (${SERVICE_USER})$ python searx/webapp.py
124+
125+ # disable debug
126+ $ sudo -H sed -i -e "s/debug : True/debug : False/g" "$SEARX_SETTINGS_PATH"
127+
128+Open WEB browser and visit http://$SEARX_INTERNAL_URL . If you are inside a
129+container or in a script, test with curl:
130+
131+.. tabs::
132+
133+ .. group-tab:: WEB browser
134+
135+ .. code-block:: sh
136+
137+ $ xgd-open http://$SEARX_INTERNAL_URL
138+
139+ .. group-tab:: curl
140+
141+ .. code-block:: none
142+
143+ $ curl --location --verbose --head --insecure $SEARX_INTERNAL_URL
144+
145+ * Trying 127.0.0.1:8888...
146+ * TCP_NODELAY set
147+ * Connected to 127.0.0.1 (127.0.0.1) port 8888 (#0)
148+ > HEAD / HTTP/1.1
149+ > Host: 127.0.0.1:8888
150+ > User-Agent: curl/7.68.0
151+ > Accept: */*
152+ >
153+ * Mark bundle as not supporting multiuse
154+ * HTTP 1.0, assume close after body
155+ < HTTP/1.0 200 OK
156+ HTTP/1.0 200 OK
157+ ...
158+
159+.. END check searx installation
docs/conf.py+2
@@ -23,6 +23,8 @@ master_doc = "index"
2323source_suffix = '.rst'
2424numfig = True
2525
26+exclude_patterns = ['build-templates/*.rst']
27+
2628from searx import webapp
2729jinja_contexts = {
2830 'webapp': dict(**webapp.__dict__)
utils/searx.sh+1−161
@@ -643,170 +643,10 @@ rst-doc() {
643643 arch="$(echo "${arch}" | sed 's/.*/ & \\/' | sed '$ s/.$//')"
644644 fedora="$(echo "${fedora}" | sed 's/.*/ & \\/' | sed '$ s/.$//')"
645645
646− cat <<EOF
647−
648−.. START distro-packages
649−
650−.. tabs::
651−
652− .. group-tab:: Ubuntu / debian
653−
654− .. code-block:: sh
655−
656− $ sudo -H apt-get install -y \\
657−${debian}
658−
659− .. group-tab:: Arch Linux
660−
661− .. code-block:: sh
662−
663− $ sudo -H pacman -S --noconfirm \\
664−${arch}
665−
666− .. group-tab:: Fedora / RHEL
667−
668− .. code-block:: sh
669−
670− $ sudo -H dnf install -y \\
671−${fedora}
672−
673−.. END distro-packages
674−
675−
676−.. START create user
677−
678−.. tabs::
679−
680− .. group-tab:: bash
681−
682− .. code-block:: sh
683−
684− $ sudo -H useradd --shell /bin/bash --system \\
685− --home-dir "$SERVICE_HOME" \\
686− --comment "Privacy-respecting metasearch engine" $SERVICE_USER
687−
688− $ sudo -H mkdir "$SERVICE_HOME"
689− $ sudo -H chown -R "$SERVICE_GROUP:$SERVICE_GROUP" "$SERVICE_HOME"
690−
691−.. END create user
692−
693−.. START clone searx
694−
695−.. tabs::
696−
697− .. group-tab:: bash
698−
699− .. code-block:: sh
700−
701− $ sudo -H -u ${SERVICE_USER} -i
702− (${SERVICE_USER})$ git clone "https://github.com/asciimoo/searx.git" "$SEARX_SRC"
703−
704−.. END clone searx
705−
706−.. START create virtualenv
707−
708−.. tabs::
709−
710− .. group-tab:: bash
711−
712− .. code-block:: sh
713−
714− (${SERVICE_USER})$ python3 -m venv "${SEARX_PYENV}"
715− (${SERVICE_USER})$ echo ". ${SEARX_PYENV}/bin/activate" >> "$SERVICE_HOME/.profile"
716−
717−.. END create virtualenv
718−
719−.. START manage.sh update_packages
720−
721−.. tabs::
722−
723− .. group-tab:: bash
724−
725− .. code-block:: sh
726−
727− $ sudo -H -u ${SERVICE_USER} -i
728−
729− (${SERVICE_USER})$ command -v python && python --version
730− $SEARX_PYENV/bin/python
731− Python 3.8.1
732−
733− (${SERVICE_USER})$ cd "$SEARX_SRC"
734− (${SERVICE_USER})$ ./manage.sh update_packages
735−
736−.. END manage.sh update_packages
737−
738−.. START searx config
739−
740−.. tabs::
741−
742− .. group-tab:: bash
743−
744− .. code-block:: sh
745−
746− $ sudo -H cp "$SEARX_SRC/searx/settings.yml" "${SEARX_SETTINGS_PATH}"
747− $ sudo -H sed -i -e "s/ultrasecretkey/\$(openssl rand -hex 16)/g" "$SEARX_SETTINGS_PATH"
748− $ sudo -H sed -i -e "s/{instance_name}/searx@\$(uname -n)/g" "$SEARX_SETTINGS_PATH"
749−
750−.. END searx config
751−
752−.. START check searx installation
753−
754−.. tabs::
755−
756− .. group-tab:: bash
757−
758− .. code-block:: sh
759−
760− # enable debug ..
761− $ sudo -H sed -i -e "s/debug : False/debug : True/g" "$SEARX_SETTINGS_PATH"
762−
763− # start webapp
764− $ sudo -H -u ${SERVICE_USER} -i
765− (${SERVICE_USER})$ cd ${SEARX_SRC}
766− (${SERVICE_USER})$ export SEARX_SETTINGS_PATH="${SEARX_SETTINGS_PATH}"
767− (${SERVICE_USER})$ python searx/webapp.py
768−
769− # disable debug
770− $ sudo -H sed -i -e "s/debug : True/debug : False/g" "$SEARX_SETTINGS_PATH"
771−
772−Open WEB browser and visit http://$SEARX_INTERNAL_URL . If you are inside a
773−container or in a script, test with curl:
774−
775−.. tabs::
776−
777− .. group-tab:: WEB browser
778−
779− .. code-block:: sh
780−
781− $ xgd-open http://$SEARX_INTERNAL_URL
782−
783− .. group-tab:: curl
784−
785− .. code-block:: none
786−
787− $ curl --location --verbose --head --insecure $SEARX_INTERNAL_URL
788−
789− * Trying 127.0.0.1:8888...
790− * TCP_NODELAY set
791− * Connected to 127.0.0.1 (127.0.0.1) port 8888 (#0)
792− > HEAD / HTTP/1.1
793− > Host: 127.0.0.1:8888
794− > User-Agent: curl/7.68.0
795− > Accept: */*
796− >
797− * Mark bundle as not supporting multiuse
798− * HTTP 1.0, assume close after body
799− < HTTP/1.0 200 OK
800− HTTP/1.0 200 OK
801− ...
802−
803−.. END check searx installation
804−
805−EOF
646+ eval "echo \"$(< ${REPO_ROOT}/docs/build-templates/searx.rst)\""
806647
807648}
808649
809−
810650# ----------------------------------------------------------------------------
811651main "$@"
812652# ----------------------------------------------------------------------------