Skip to content

Commit 5209daf

Browse files
cdpxecdpxe
authored
Merge pull request #52 from oleludwig/mkdocs-migration
Migrate documentation to markdown and generate website with mkdocs
2 parents 09f410b + eb71ec1 commit 5209daf

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+1269
-4751
lines changed

‎.github/workflows/gh-pages.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
name: Deploy documentation to Pages
2+
3+
on:
4+
push:
5+
branches: ["master"]
6+
workflow_dispatch:
7+
8+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
15+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
16+
concurrency:
17+
group: "pages"
18+
cancel-in-progress: false
19+
20+
jobs:
21+
build:
22+
runs-on: ubuntu-latest
23+
steps:
24+
- name: Checkout
25+
uses: actions/checkout@v4
26+
- name: Setup Pages
27+
uses: actions/configure-pages@v5
28+
- name: Setup Python
29+
uses: actions/setup-python@v6
30+
with:
31+
python-version: '3.13'
32+
- name: Install mkdocs
33+
run: pip install mkdocs
34+
- name: Install pandoc and Latex
35+
run: sudo apt-get update -y && sudo apt-get install -y pandoc texlive texlive-latex-extra
36+
- name: Build static files
37+
run: |
38+
cd docs
39+
make
40+
mv docs.pdf site/
41+
- name: Upload artifact
42+
uses: actions/upload-pages-artifact@v3
43+
with:
44+
path: docs/site/
45+
deploy:
46+
environment:
47+
name: github-pages
48+
url: ${{ steps.deployment.outputs.page_url }}
49+
runs-on: ubuntu-latest
50+
needs: build
51+
steps:
52+
- name: Deploy to GitHub Pages
53+
id: deployment
54+
uses: actions/deploy-pages@v4

‎CHANGELOG‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,11 @@ MISC:
152152
- Improve the detection of root privileges in the script
153153
create_certificate.
154154
- Switch license of the file wendzelnntpd.SlackBuild to GPLv3
155+
- Migrate the source code of the documentation from latex to markdown.
156+
Generate the HTML version of the documentation with mkdocs and make it
157+
available under https://cdpxe.github.io/WendzelNNTPd/. Generate the PDF
158+
version of the documentation with pandoc and make it available under
159+
https://cdpxe.github.io/WendzelNNTPd/docs.pdf.
155160

156161
2.1.3-stable "Friedrichroda" : 17-Apr-2021:
157162
As usual, every new release gets named after a nice travel location.

‎INSTALL‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,9 @@ Installing and Upgrading WendzelNNTPd under Linux/BSD/*nix:
22
===========================================================
33

44
IMPORTANT NOTE: Please note that the entire documentation can be found
5-
in the directory ./docs/ (.tex files and .pdf file) as well as in the
6-
directory ./docs/docs (.html files).
7-
8-
You can compile the latex code into PDF and HTML by using the Makefile
9-
contained in ./docs. However, there should be PDF and HTML files
10-
already present by default. Also, the PDF file should always be
11-
available on the online repository under ./docs.
5+
in the directory ./docs/docs/ (.md files).
126

7+
You can compile the Markdown files into PDF and HTML by using the Makefile
8+
contained in ./docs. The HTML website and PDF file are also available online
9+
under https://cdpxe.github.io/WendzelNNTPd/ and
10+
https://cdpxe.github.io/WendzelNNTPd/docs.pdf.

‎Makefile.in‎

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -58,8 +58,9 @@ GDBON=-ggdb -g #-lefence
5858
DEBUG=$(GDBON) -DDEBUG -DXXDEBUG
5959

6060
# The list of documentation files we wish to install
61-
DOCFILES_TO_INST=AUTHORS CHANGELOG HISTORY README.md INSTALL LICENSE database/usenet.db_struct database/mysql_db_struct.sql docs/docs.pdf
61+
DOCFILES_TO_INST=AUTHORS CHANGELOG HISTORY README.md INSTALL LICENSE database/usenet.db_struct database/mysql_db_struct.sql
6262
MANPAGES=docs/wendzelnntpd.8 docs/wendzelnntpadm.8
63+
HTML_DOC_DIRS=$(shell cd docs/ && find site/ -type d)
6364

6465
all : wendzelnntpadm main.o log.o database.o cdpstrings.o server.o lexyacc charstack.o libfunc.o acl.o db_abstraction.o hash.o $(SQLITEOBJ) $(MYSQLOBJ) $(POSTGRESOBJ) $(OPENSSLOBJ) globals.o scripts/startup/init.d_script
6566
expr `cat build` \+ 1 >build
@@ -144,7 +145,9 @@ install : bin/wendzelnntpd bin/wendzelnntpadm
144145
if [ ! -d $(DESTDIR)$(sysconfdir) ]; then $(INSTALL) -d -m 0755 $(DESTDIR)$(sysconfdir); fi
145146
if [ ! -d $(DESTDIR)$(sbindir) ]; then $(INSTALL) -d -m 0755 $(DESTDIR)$(sbindir); fi
146147
if [ ! -d $(DESTDIR)$(docdir) ]; then $(INSTALL) -d -m 0755 $(DESTDIR)$(docdir); fi
147-
if [ ! -d $(DESTDIR)$(docdir)/docs ]; then $(INSTALL) -d -m 0755 $(DESTDIR)$(docdir)/docs; fi
148+
for dir in `cd docs/ && find site/ -type d`; do \
149+
if [ ! -d $(DESTDIR)$(docdir)/$$dir ]; then $(INSTALL) -d -m 0755 $(DESTDIR)$(docdir)/$$dir; fi \
150+
done
148151
if [ ! -d $(DESTDIR)$(man8dir) ]; then $(INSTALL) -d -m 0755 $(DESTDIR)$(man8dir); fi
149152
# nextmsgid and database/usenet.db are placed here:
150153
# og-rwx since the passwords are stored in the database too!
@@ -154,7 +157,10 @@ install : bin/wendzelnntpd bin/wendzelnntpadm
154157
$(INSTALL_PROGRAM) bin/wendzelnntpd bin/wendzelnntpadm $(DESTDIR)$(sbindir)/
155158
# documentation and config files
156159
$(INSTALL_DATA) $(DOCFILES_TO_INST) $(DESTDIR)$(docdir)/
157-
$(INSTALL_DATA) docs/docs/* $(DESTDIR)$(docdir)/docs/
160+
-$(INSTALL_DATA) docs/docs.pdf $(DESTDIR)$(docdir)/
161+
-for file in `cd docs/ && find site/ -type f`; do \
162+
$(INSTALL_DATA) docs/$$file $(DESTDIR)$(docdir)/$$file; \
163+
done
158164
# manpages
159165
$(INSTALL_DATA) $(MANPAGES) $(DESTDIR)$(man8dir)
160166
# config
@@ -181,7 +187,14 @@ upgrade : bin/wendzelnntpd bin/wendzelnntpadm
181187
$(INSTALL_PROGRAM) bin/wendzelnntpd bin/wendzelnntpadm $(DESTDIR)$(sbindir)/
182188
# documentation
183189
$(INSTALL_DATA) $(DOCFILES_TO_INST) $(DESTDIR)$(docdir)/
184-
$(INSTALL_DATA) docs/docs/* $(DESTDIR)$(docdir)/docs/
190+
-$(INSTALL_DATA) docs/docs.pdf $(DESTDIR)$(docdir)/
191+
for dir in `cd docs/ && find site/ -type d`; do \
192+
if [ ! -d $(DESTDIR)$(docdir)/$$dir ]; then $(INSTALL) -d -m 0755 $(DESTDIR)$(docdir)/$$dir; fi \
193+
done
194+
-for file in `cd docs/ && find site/ -type f`; do \
195+
$(INSTALL_DATA) docs/$$file $(DESTDIR)$(docdir)/$$file; \
196+
done
197+
-rm -rf $(DESTDIR)$(docdir)/docs
185198
# manpages
186199
$(INSTALL_DATA) $(MANPAGES) $(DESTDIR)$(man8dir)
187200
@echo "Upgrade finished. Thank you for upgrading and using this software. Have fun!"
@@ -200,11 +213,7 @@ clean :
200213
y.output gpmon.out log *.BAK lex.*.[ch] *.tab.[ch] `find . -name '*~'` \
201214
config.output temp.c
202215
@# documentation cleanup
203-
rm -f docs/docs.ilg docs/docs.ind docs/*.idx docs/*.aux docs/*.toc \
204-
docs/*.log docs/docs.out \
205-
docs/docs/*.tex docs/docs/*.pl docs/docs/*.log docs/docs/*.idx \
206-
docs/docs/WARNINGS docs/docs/*.old docs/docs/*.aux docs/docs/images.out \
207-
docs/docs/images.pdf docs/docs/crossref.png
216+
cd docs && $(MAKE) clean
208217
rm -f $(srcdir)/scripts/startup/init.d_script
209218

210219
print_version :

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,12 +55,12 @@ Read my [blog posting on WendzelNNTPd](http://www.wendzel.de/misc/2021/01/04/new
5555

5656
## More Information
5757
- List of contributors [https://github.com/cdpxe/WendzelNNTPd/blob/master/AUTHORS](https://github.com/cdpxe/WendzelNNTPd/blob/master/AUTHORS)
58-
- Website: [https://cdpxe.github.io/WendzelNNTPd/](https://cdpxe.github.io/WendzelNNTPd/)
5958
- Forum for your Questions and Comments: [https://sourceforge.net/p/wendzelnntpd/discussion/general/](https://sourceforge.net/p/wendzelnntpd/discussion/general/)
6059

6160
## Documentation
6261

63-
The documentation can be found [here](https://github.com/cdpxe/WendzelNNTPd/blob/master/docs/docs.pdf).
62+
The documentation can be found [here](https://cdpxe.github.io/WendzelNNTPd/).
63+
It is also available as a PDF file [here](https://cdpxe.github.io/WendzelNNTPd/docs.pdf).
6464

6565
## Propaganda
6666
Some late 1990's/early 2000's-styled 'powered by' logos. Let me know if you include these into your websites.

‎docs/.gitignore‎

Lines changed: 2 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,2 @@
1-
*.aux
2-
*.bbl
3-
*.bcf
4-
*.blg
5-
*.lof
6-
*.lot
7-
*.out
8-
*.lol
9-
*.run.xml
10-
*.synctex.gz
11-
*.toc
12-
*.log
13-
*.idx
14-
*.ilg
15-
*.ind
1+
site/
2+
docs.pdf

‎docs/Makefile‎

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,23 @@
1-
all :
2-
rm -vf docs.{aux,bbl,blg,dvi,ilg,ind,lof,log,lot,ps,pdf,toc,nlo,nls}
3-
pdflatex docs.tex
4-
#makeindex docs
5-
pdflatex docs.tex
6-
makeindex docs
7-
pdflatex docs.tex
1+
# List of the mardown files which should be included in the pdf documentation.
2+
# The order of the files corresponds to the order of the chapters in the PDF.
3+
DOCFILES=docs/index.md docs/install.md docs/configuration.md docs/running.md docs/development.md docs/upgrade.md
84

9-
#pdf :
10-
# pdflatex docs.tex
5+
all : site docs.pdf
116

12-
v :
7+
site : mkdocs.yml $(DOCFILES)
8+
mkdocs build
9+
10+
docs.pdf : template.tex $(DOCFILES)
11+
pandoc --from markdown+gfm_auto_identifiers+footnotes $(DOCFILES) --template template.tex --top-level-division=chapter --lua-filter=convert-links.lua -s -o docs.pdf
12+
13+
v : docs.pdf
1314
evince docs.pdf || atril docs.pdf || open docs.pdf
1415

1516
view : v
1617

17-
latex2html :
18-
latex2html -show_section_numbers -local_icons -split 2 docs.tex
18+
serve-html :
19+
mkdocs serve
1920

21+
clean :
22+
rm -f docs.pdf
23+
rm -rf site/

0 commit comments

Comments
 (0)