diff options
Diffstat (limited to 'docs')
35 files changed, 3388 insertions, 0 deletions
diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..e602d24 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = -v +SPHINXBUILD = sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/ablog.ico b/docs/_static/ablog.ico Binary files differnew file mode 100644 index 0000000..31b1671 --- /dev/null +++ b/docs/_static/ablog.ico diff --git a/docs/_static/ablog.png b/docs/_static/ablog.png Binary files differnew file mode 100644 index 0000000..fc21bf3 --- /dev/null +++ b/docs/_static/ablog.png diff --git a/docs/_static/ablog.svg b/docs/_static/ablog.svg new file mode 100644 index 0000000..aa80a42 --- /dev/null +++ b/docs/_static/ablog.svg @@ -0,0 +1,949 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg + xmlns:dc="https://purl.org/dc/elements/1.1/" + xmlns:cc="https://creativecommons.org/ns#" + xmlns:rdf="https://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="https://www.w3.org/2000/svg" + xmlns="https://www.w3.org/2000/svg" + xmlns:sodipodi="https://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="https://www.inkscape.org/namespaces/inkscape" + height="1200" + width="3600" + id="svg4026" + version="1.1" + inkscape:version="0.48.2 r9819" + sodipodi:docname="ablog.svg" + inkscape:export-filename="/Users/abakan/Documents/GitHub/ablog/docs/_static/ablog.png" + inkscape:export-xdpi="5.0250001" + inkscape:export-ydpi="5.0250001"> + <metadata + id="metadata4034"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="https://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <defs + id="defs4032"> + <filter + id="filter3248" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur3250" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend3252" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence3254" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap3256" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology3258" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend3260" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter3262" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur3264" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend3266" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence3268" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap3270" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology3272" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend3274" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter3385" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur3387" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend3389" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence3391" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap3393" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology3395" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend3397" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter3399" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur3401" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend3403" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence3405" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap3407" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology3409" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend3411" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter3413" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur3415" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend3417" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence3419" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap3421" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology3423" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend3425" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter3427" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur3429" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend3431" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence3433" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap3435" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology3437" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend3439" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter3441" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur3443" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend3445" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence3447" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap3449" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology3451" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend3453" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter3455" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur3457" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend3459" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence3461" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap3463" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology3465" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend3467" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter3950" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur3952" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend3954" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence3956" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap3958" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology3960" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend3962" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter3964" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur3966" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend3968" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence3970" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap3972" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology3974" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend3976" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter3978" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur3980" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend3982" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence3984" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap3986" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology3988" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend3990" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter3992" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur3994" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend3996" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence3998" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap4000" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology4002" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend4004" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter4006" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur4008" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend4010" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence4012" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap4014" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology4016" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend4018" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter4020" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur4022" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend4024" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence4026" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap4028" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology4030" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend4032" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter4397" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur4399" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend4401" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence4403" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap4405" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology4407" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend4409" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter4411" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur4413" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend4415" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence4417" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap4419" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology4421" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend4423" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter4425" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur4427" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend4429" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence4431" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap4433" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology4435" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend4437" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter4439" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur4441" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend4443" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence4445" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap4447" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology4449" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend4451" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter4453" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur4455" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend4457" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence4459" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap4461" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology4463" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend4465" + in2="result2" + mode="screen" /> + </filter> + <filter + id="filter4467" + inkscape:label="Air spray" + inkscape:menu="Scatter" + inkscape:menu-tooltip="Convert to small scattered particles with some thickness" + width="2" + height="2" + y="-0.5" + x="-0.5" + color-interpolation-filters="sRGB"> + <feGaussianBlur + id="feGaussianBlur4469" + stdDeviation="0.01" + result="result1" /> + <feBlend + id="feBlend4471" + in2="result1" + result="fbSourceGraphic" + mode="multiply" /> + <feTurbulence + id="feTurbulence4473" + baseFrequency="0.8" + type="fractalNoise" + seed="0" + numOctaves="3" + result="result3" /> + <feDisplacementMap + id="feDisplacementMap4475" + in2="result3" + in="fbSourceGraphic" + xChannelSelector="R" + yChannelSelector="G" + scale="50" + result="result2" /> + <feMorphology + id="feMorphology4477" + radius="1" + operator="dilate" + result="result4" /> + <feBlend + id="feBlend4479" + in2="result2" + mode="screen" /> + </filter> + </defs> + <sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="1286" + inkscape:window-height="1009" + id="namedview4030" + showgrid="false" + inkscape:zoom="0.236" + inkscape:cx="2155.7813" + inkscape:cy="500" + inkscape:window-x="401" + inkscape:window-y="175" + inkscape:window-maximized="0" + inkscape:current-layer="svg4026" /> + <text + xml:space="preserve" + style="font-size:1160px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial Rounded MT Bold;-inkscape-font-specification:'Arial Rounded MT Bold,'" + x="944.91528" + y="907.62714" + id="text3784" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan3786" + x="944.91528" + y="907.62714" + style="font-size:1160px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#000000;font-family:Arial Rounded MT Bold;-inkscape-font-specification:'Arial Rounded MT Bold,'">Blog</tspan></text> + <path + d="M 833.65625 83.84375 C 701.98958 83.84375 580.11458 116.55208 468.03125 181.96875 C 355.94792 247.38542 267.40625 336.13542 202.40625 448.21875 C 137.40625 560.30208 104.90625 682.17708 104.90625 813.84375 C 104.90625 843.01042 115.11458 867.59375 135.53125 887.59375 C 155.94792 907.59375 180.32292 917.59375 208.65625 917.59375 C 236.98958 917.59375 261.36458 907.59375 281.78125 887.59375 C 302.19792 867.59375 312.40625 843.01042 312.40625 813.84375 C 312.40625 669.67708 363.44792 546.76042 465.53125 445.09375 C 567.61458 343.42708 690.32292 292.59375 833.65625 292.59375 C 861.98958 292.59375 886.36458 282.59375 906.78125 262.59375 C 927.19792 242.59375 937.40625 218.01042 937.40625 188.84375 C 937.40625 159.67708 927.19792 134.88542 906.78125 114.46875 C 886.36458 94.052083 861.98958 83.84375 833.65625 83.84375 z M 833.65625 396.375 C 753.11275 396.375 699.43885 415.49755 674.84375 425.96875 C 652.66285 435.41205 632.55455 445.84635 604.28125 465.34375 C 577.68735 483.68305 558.5651 513.6848 559.625 547.0625 C 560.5463 576.0772 562.6609 593.9731 583.6875 617.625 C 611.3285 648.7173 626.15755 648.26095 641.28125 652.46875 C 667.09175 659.64985 699.51095 650.3316 716.21875 640.5625 C 727.78705 633.7985 737.68565 628.10535 746.46875 623.84375 L 746.46875 808.4375 C 746.39575 810.2263 746.375 812.0521 746.375 813.875 C 746.375 843.0417 755.7673 867.625 774.5625 887.625 C 793.3577 907.625 815.7919 917.625 841.875 917.625 C 867.9582 917.625 890.3923 907.625 909.1875 887.625 C 927.9827 867.625 937.40625 843.0417 937.40625 813.875 C 937.40625 813.3721 937.38 812.8754 937.375 812.375 L 937.46875 812.375 L 937.46875 509.75 L 937.09375 509.75 C 937.28755 506.9953 937.40625 504.2168 937.40625 501.375 C 937.40625 472.2084 927.19785 447.4167 906.78125 427 C 886.36455 406.5834 861.98955 396.375 833.65625 396.375 z M 521 709.09375 C 492.66667 709.09375 468.29167 719.30208 447.875 739.71875 C 427.45833 760.13542 417.25 784.92708 417.25 814.09375 C 417.25 843.26042 427.45833 867.84375 447.875 887.84375 C 468.29167 907.84375 492.66667 917.84375 521 917.84375 C 549.33333 917.84375 573.70833 907.84375 594.125 887.84375 C 614.54167 867.84375 624.75 843.26042 624.75 814.09375 C 624.75 784.92708 614.54167 760.13542 594.125 739.71875 C 573.70833 719.30208 549.33333 709.09375 521 709.09375 z " + id="path3094-3" /> +</svg> diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..8c88230 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,151 @@ +import re +from pathlib import Path + +from packaging.version import parse as _parse +from sphinx import addnodes + +import ablog + +ablog_builder = "dirhtml" +ablog_website = "_website" +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.doctest", + "sphinx.ext.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.ifconfig", + "sphinx.ext.extlinks", + "sphinx_automodapi.automodapi", + "ablog", + "alabaster", + "nbsphinx", + "myst_parser", +] + +version = str(_parse(ablog.__version__)) +project = "ABlog" +copyright = "2014-2022, ABlog Team" +master_doc = "index" +source_suffix = { + ".rst": "restructuredtext", + ".md": "markdown", +} +exclude_patterns = ["_build", "docs/manual/.ipynb_checkpoints"] +html_title = "ABlog" +html_use_index = True +html_domain_indices = False +html_show_sourcelink = True +html_favicon = "_static/ablog.ico" +blog_title = "ABlog" +blog_baseurl = "https://ablog.readthedocs.io/" +blog_locations = { + "Pittsburgh": ("Pittsburgh, PA", "https://en.wikipedia.org/wiki/Pittsburgh"), + "San Fran": ("San Francisco, CA", "https://en.wikipedia.org/wiki/San_Francisco"), + "Denizli": ("Denizli, Turkey", "https://en.wikipedia.org/wiki/Denizli"), +} +blog_languages = { + "en": ("English", None), + "nl": ("Nederlands", None), + "zh_CN": ("Chinese", None), +} +blog_default_language = "en" +language = "en" +blog_authors = { + "Ahmet": ("Ahmet Bakan", "https://ahmetbakan.com"), + "Luc": ("Luc Saffre", "https://saffre-rumma.net/luc/"), + "Mehmet": ("Mehmet Gerçeker", "https://github.com/mehmetg"), + "Libor": ("Libor Jelínek", "https://liborjelinek.github.io/"), +} +blog_feed_archives = True +blog_feed_fulltext = True +blog_feed_templates = { + "atom": { + "content": "{{ title }}{% for tag in post.tags %}" " #{{ tag.name|trim()|replace(' ', '') }}" "{% endfor %}", + }, + "social": { + "content": "{{ title }}{% for tag in post.tags %}" " #{{ tag.name|trim()|replace(' ', '') }}" "{% endfor %}", + }, +} +disqus_shortname = "https-ablog-readthedocs-io" +disqus_pages = True +fontawesome_link_cdn = "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css" +html_theme = "alabaster" +html_sidebars = { + "**": [ + "about.html", # Comes from alabaster + "searchfield.html", # Comes from alabaster + "ablog/postcard.html", + "ablog/recentposts.html", + "ablog/tagcloud.html", + "ablog/categories.html", + "ablog/archives.html", + "ablog/authors.html", + "ablog/languages.html", + "ablog/locations.html", + ] +} +html_theme_options = { + "travis_button": False, + "github_user": "sunpy", + "github_repo": "ablog", + "description": "ABlog for blogging with Sphinx", + "logo": "ablog.png", +} +intersphinx_mapping = { + "python": ("https://docs.python.org/", None), + "sphinx": ("https://www.sphinx-doc.org/en/master/", None), +} +extlinks = { + "wiki": ("https://en.wikipedia.org/wiki/%s", "%s"), + "issue": ("https://github.com/sunpy/ablog/issues/%s", "issue %s"), + "pull": ("https://github.com/sunpy/ablog/pull/%s", "pull request %s"), +} +rst_epilog = """ +.. _Sphinx: http://sphinx-doc.org/ +.. _Python: https://python.org +.. _Disqus: https://disqus.com/ +.. _GitHub: https://github.com/sunpy/ablog +.. _PyPI: https://pypi.python.org/pypi/ablog +.. _Read The Docs: https://readthedocs.org/ +.. _Alabaster: https://github.com/bitprophet/alabaster +""" +locale_dirs = [str(Path(ablog.__file__).parent / Path("locales"))] +nitpicky = True +nitpick_ignore = [] +for line in open("nitpick-exceptions"): + if line.strip() == "" or line.startswith("#"): + continue + dtype, target = line.split(None, 1) + target = target.strip() + nitpick_ignore.append((dtype, target)) + + +def parse_event(env, sig, signode): + event_sig_re = re.compile(r"([a-zA-Z-]+)\s*\((.*)\)") + m = event_sig_re.match(sig) + if not m: + signode += addnodes.desc_name(sig, sig) + return sig + name, args = m.groups() + signode += addnodes.desc_name(name, name) + plist = addnodes.desc_parameterlist() + for arg in args.split(","): + arg = arg.strip() + plist += addnodes.desc_parameter(arg, arg) + signode += plist + return name + + +def setup(app): + from sphinx.ext.autodoc import cut_lines + from sphinx.util.docfields import GroupedField + + app.connect("autodoc-process-docstring", cut_lines(4, what=["module"])) + app.add_object_type( + "confval", + "confval", + objname="configuration value", + indextemplate="pair: %s; configuration value", + ) + fdesc = GroupedField("parameter", label="Parameters", names=["param"], can_collapse=True) + app.add_object_type("event", "event", "pair: %s; event", parse_event, doc_field_types=[fdesc]) diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..407451f --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,104 @@ +ABlog for Sphinx +================ + +ABlog is a Sphinx extension that converts any documentation or personal website project into a full-fledged blog with: + + * :ref:`Atom feeds <blog-feed>` + * :ref:`Archive pages <blog-archives>` + * :ref:`sidebars` + * :ref:`disqus-integration` + * :ref:`Font-Awesome integration <font-awesome>` + * :doc:`manual/markdown` + +Ablog is part of the `SunPy Project <https://www.sunpy.org>`__. + +.. _installation: + +Installation +------------ + +You can install ABlog using `pip <https://pip.pypa.io/en/stable/>`__:: + + pip install -U ablog + +or `miniforge <https://github.com/conda-forge/miniforge>`__:: + + conda install ablog + +This will also install `Sphinx <http://sphinx-doc.org/>`__, `feedgen <https://github.com/lkiesow/python-feedgen>`__, and `Invoke <https://www.pyinvoke.org/>`__ respectively required for building your website, making it look good, generating feeds, and running deploy commands. + +Getting Started +--------------- + +If you are starting a new project, see the :ref:`quick-start` guide. +If you already have a project, enable blogging by making following changes in ``conf.py``: + +.. code-block:: python + + # 1. Add 'ablog' and 'sphinx.ext.intersphinx' to the list of extensions + extensions = [ + '...', + 'ablog', + 'sphinx.ext.intersphinx', + ] + +How it works +------------ + +If you are new to Sphinx_ and reStructuredText markup language, you might find `reStructuredText Primer`_ useful. +Once you have content (in ``.rst`` files), you can post *any page* using the :rst:dir:`post` directive as follows: + +.. _reStructuredText Primer: https://www.sphinx-doc.org/en/master/ + +.. code-block:: rst + + .. post:: Apr 15, 2014 + :tags: earth, love, peace + :category: python + :author: me + :location: SF + :language: en + +An alternative method is: + +.. code-block:: rst + + :blogpost: true + :date: Oct 10, 2020 + :author: Nabil Freij + :location: World + :category: Manual + :language: English + +at the top of the file. + +ABlog will index all files posted as above and list them in archives and feeds specified in ``:tag:``, ``:category:``, etc. options. + +You can also include a list of posts using :rst:dir:`postlist` directive: + +.. code-block:: rst + + .. postlist:: + :list-style: circle + :category: Manual + :format: {title} + :sort: + +For ABlog documentation, this converts to the following where you can find more about configuring and using ABlog: + +.. postlist:: + :category: Manual + :list-style: circle + :format: {title} + :sort: + +.. only:: html + + .. image:: https://readthedocs.org/projects/ablog/badge/?version=latest + :target: https://ablog.readthedocs.io + +.. toctree:: + :hidden: + :glob: + + */* diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..d85ed39 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs/manual/ablog-commands.rst b/docs/manual/ablog-commands.rst new file mode 100644 index 0000000..c50cbd7 --- /dev/null +++ b/docs/manual/ablog-commands.rst @@ -0,0 +1,178 @@ +.. _commands: + +ABlog Commands +============== + +.. post:: Mar 1, 2015 + :tags: config, commands + :author: Ahmet, Mehmet + :category: Manual + :location: SF + + +``ablog`` commands are for streamlining blog operations, i.e. building, serving, and viewing blog pages, as well as starting a new blog:: + + $ ablog + usage: ablog [-h] [-v] {start,build,clean,serve,post,deploy} ... + + ABlog for blogging with Sphinx + + optional arguments: + -h, --help show this help message and exit + -v, --version print ABlog version and exit + + subcommands: + {start,build,clean,serve,post,deploy} + start start a new blog project + build build your blog project + clean clean your blog build files + serve serve and view your project + post create a blank post + deploy deploy your website build files + + See 'ablog <command> -h' for more information on a specific command. + +.. contents:: Here are all the things you can do: + :local: + :backlinks: top + +.. _start: + +Start a New Project +------------------- + +``ablog start`` command is for quickly setting up a blog project. +See :ref:`quick-start` for how it works and what it prepares for you:: + + $ ablog start -h + usage: ablog start [-h] + + Start a new blog project by answering a few questions. You will end up with a + configuration file and sample pages. + + optional arguments: + -h, --help show this help message and exit + +.. _build: + +Build your Website +------------------ + +Running ``ablog build`` in your project folder builds your website HTML pages:: + + $ ablog build -h + usage: ablog build [-h] [-a] [-b BUILDER] [-s SOURCEDIR] [-w WEBSITE] + [-d DOCTREES] [-T] [-P] + + Path options can be set in conf.py. Default values of paths are relative to + conf.py. + + optional arguments: + -h, --help show this help message and exit + -a write all files; default is to only write new and changed + files + -b BUILDER builder to use, default `ablog_builder` or dirhtml + -s SOURCEDIR root path for source files, default is path to the folder that + contains conf.py + -w WEBSITE path for website, default is _website when `ablog_website` is + not set in conf.py + -d DOCTREES path for the cached environment and doctree files, default + .doctrees when `ablog_doctrees` is not set in conf.py + -T show full traceback on exception + -P run pdb on exception + +Serve and View Locally +---------------------- + +Running ``ablog serve``, after building your website, will start a Python server and open up browser tab to view your website:: + + $ ablog serve -h + usage: ablog serve [-h] [-w WEBSITE] [-p PORT] [-n] [-r] [--patterns] + + Serve options can be set in conf.py. Default values of paths are relative to + conf.py. + + optional arguments: + -h, --help show this help message and exit + -w WEBSITE path for website, default is _website when `ablog_website` is + not set in conf.py + -p PORT port number for HTTP server; default is 8000 + -n do not open website in a new browser tab + -r rebuild when a file matching patterns change or get added + --patterns patterns for triggering rebuilds + +.. _deploy: + +Deploy to GitHub Pages +---------------------- + +Running ``ablog deploy`` will push your website to GitHub:: + + $ ablog deploy -h + usage: ablog deploy [-h] [-w WEBSITE] [-p REPODIR] [-g GITHUB_PAGES] + [-m MESSAGE] [-f] [--push-quietly] + [--github-branch GITHUB_BRANCH] [--github-ssh] + [--github-token GITHUB_TOKEN] [--github-url GITHUB_URL] + + Path options can be set in conf.py. Default values of paths are relative to + conf.py. + + options: + -h, --help show this help message and exit + -w WEBSITE path for website, default is _website when + `ablog_website` is not set in conf.py + -p REPODIR path to the location of repository to be deployed, e.g. + `../username.github.io`, default is folder containing + `conf.py` + -g GITHUB_PAGES GitHub username for deploying to GitHub pages + -m MESSAGE commit message + -f overwrite last commit, i.e. `commit --amend; push -f` + --push-quietly be more quiet when pushing changes + --github-branch GITHUB_BRANCH + Branch to use. Default is 'master'. + --github-ssh use ssh when cloning website + --github-token GITHUB_TOKEN + environment variable name storing GitHub access token + --github-url GITHUB_URL + Custom GitHub URL. Useful when multiple accounts are + configured on the same machine. Default is: + git@github.com + + +Create a Post +------------- + +Finally, ``ablog post`` will make a new post template file:: + + $ ablog post -h + usage: ablog post [-h] [-t TITLE] filename + + positional arguments: + filename filename, e.g. my-nth-post (.rst appended) + + optional arguments: + -h, --help show this help message and exit + -t TITLE post title; default is formed from filename + +Clean Build Files +----------------- + +In case you needed, running ``ablog clean`` will remove build files and do a deep clean with ``-D`` option:: + + $ ablog clean -h + usage: ablog clean [-h] [-d DOCTREES] [-w WEBSITE] [-D] + + Path options can be set in conf.py. Default values of paths are relative to + conf.py. + + optional arguments: + -h, --help show this help message and exit + -d DOCTREES path for the cached environment and doctree files, default + .doctrees when `ablog_doctrees` is not set in conf.py + -w WEBSITE path for website, default is _website when `ablog_website` is + not set in conf.py + -D deep clean, remove cached environment and doctree files + +.. update:: Apr 7, 2015 + + Added ``ablog clean`` and ``ablog deploy`` commands. diff --git a/docs/manual/ablog-configuration-options.rst b/docs/manual/ablog-configuration-options.rst new file mode 100644 index 0000000..9b25fb3 --- /dev/null +++ b/docs/manual/ablog-configuration-options.rst @@ -0,0 +1,291 @@ +.. _config: + +ABlog Configuration Options +=========================== + +.. post:: May 10, 2014 + :tags: config + :author: Ahmet + :category: Manual + :location: Pittsburgh + + +This post describes ABlog configuration options that go in :ref:`Sphinx build configuration file <sphinx:build-config>`. + +General options +--------------- + +.. confval:: blog_path + + A path relative to the configuration directory for blog archive pages. + Default is ``'blog'``. + +Authors, languages, & locations +------------------------------- + +.. confval:: blog_authors + + A dictionary of author names mapping to author full display names and links. + Dictionary keys are what should be used in ``post`` directive to refer to the author. + Default is ``{}``. + Example:: + + blog_authors = { + 'Ahmet': ('Ahmet Bakan', 'http://ahmetbakan.com'), + 'Durden': ('Tyler Durden', + 'https://en.wikipedia.org/wiki/Tyler_Durden'), + } + +.. confval:: blog_default_author + + Name of the default author defined in :confval:`blog_authors`. + Default is ``None``. + +.. confval:: blog_languages + + A dictionary of language code names mapping to full display names and links of these languages. + Similar to :confval:`blog_authors`, dictionary keys should be used in ``post`` directive to refer to the locations. + Default is ``{}``. + Example:: + + blog_languages = { + 'en': ('English', None), + } + +.. confval:: blog_default_language + + Code name of the default language defined in :confval:`blog_languages`. + Default is ``None``. + +.. confval:: blog_locations + + A dictionary of location names mapping to full display names and links of these locations. + Similar to :confval:`blog_authors`, dictionary keys should be used in ``post`` directive to refer to the locations. + Default is ``{}``. + +.. confval:: blog_default_location + + Name of the default location defined in :confval:`blog_locations`. + Default is ``None``. + +.. update:: Sep 15, 2014 + + Added :confval:`blog_languages` and :confval:`blog_default_language` configuration variables. + +Post related +------------ + +.. confval:: post_date_format + + Date display format (default is ``'%b %d, %Y'``, e.g., ``12 August 2024``) for published posts that goes as input to :meth:`datetime.date.strftime`. + +.. confval:: post_date_format_short + + Date display format in recent posts sidebar (default is ``'%d %B'``, e.g., ``12 October``) for published posts that goes as input to :meth:`datetime.date.strftime`. + +.. confval:: post_auto_excerpt + + Number of paragraphs (default is ``1``) that will be displayed as an excerpt from the post. + Setting this ``0`` will result in displaying no post excerpt in archive pages. + This option can be set on a per post basis using :rst:dir:`post` directive option ``excerpt``. + + See :ref:`post-excerpts-and-images` for a more detailed discussion. + +.. confval:: post_auto_image + + Index of the image that will be displayed in the excerpt of the post. + Default is ``0``, meaning no image. + Setting this to ``1`` will include the first image, when available, to the excerpt. + This option can be set on a per post basis using :rst:dir:`post` directive option ``image``. + +.. confval:: post_redirect_refresh + + Number of seconds (default is ``5``) that a redirect page waits before refreshing the page to redirect to the post. + +.. confval:: post_always_section + + When ``True``, post title and excerpt is always taken from the section that contains the :rst:dir:`post` directive, instead of the document. + This is the behavior when :rst:dir:`post` is used multiple times in a document. + Default is ``False``. + +.. confval:: post_show_prev_next + + When ``True``, links to the previous and next posts will be rendered at the bottom of the page. + Default is ``True`` + +Blog feeds +---------- + +Turn feeds on by setting :confval:`blog_baseurl` configuration variable. + +.. confval:: blog_baseurl + + Base URL for the website, turns on generating feeds. E.g., ``https://ablog.readthedocs.io``. + +Then optionally set the following: + +.. confval:: blog_title + + The “title” for the blog, used in feeds title (not archive web pages title). Default is ``'Blog'``. + +.. confval:: blog_archive_titles + + Choose to archive only post titles in collection pages, default is ``False``. + +.. confval:: blog_feed_archives + + Choose to create feeds per author, location, tag, category, and year, default is ``False``. + +.. confval:: blog_feed_fulltext + + Choose to display full text in blog feeds, default is ``False``. + +.. confval:: blog_feed_subtitle + + Blog feed subtitle, default is ``None``. + +.. confval:: blog_feed_titles + + Choose to feed only post titles, default is ``False``. + +.. confval:: blog_feed_templates + + A dictionary of feed filename roots mapping to nested dictionaries of feed entry + elements, ``title``, ``summary``, and/or ``content``, and a `Jinja2`_ template which will be + used to render the value used for that element in that feed. Templates are rendered + with the the following context: + - ``feed_length`` + - ``feed_fulltext`` + - ``feed_posts`` + - ``pagename`` + - ``feed_title`` + - ``feed_url`` + - ``feed`` + - ``post`` + - ``post_url`` + - ``content`` + - ``feed_entry`` + - ``title`` + - ``summary`` + - ``blog`` + - ``url`` + - ``app`` + Default is: ``{"atom": {}}`` + Example to add an additional feed for posting to social media:: + + blog_feed_templates = { + # Use defaults, no templates + "atom": {}, + # Create content text suitable posting to social media + "social": { + # Format tags as hashtags and append to the content + "content": "{{ title }}{% for tag in post.tags %}" + " #{{ tag.name|trim()|replace(' ', '') }}" + "{% endfor %}", + }, + } + +.. confval:: blog_feed_length + + Specify number of recent posts to include in feeds, default is ``None`` for all posts. + +.. update:: Aug 24, 2014 + + Added :confval:`blog_feed_archives`, :confval:`blog_feed_fulltext`, :confval:`blog_feed_subtitle`, and :confval:`post_always_section` options. + +.. update:: Nov 27, 2014 + + Added :confval:`blog_feed_titles`, :confval:`blog_feed_length`, and :confval:`blog_archive_titles` options. + +.. update:: Mar 20, 2021 + + Added :confval:`blog_feed_templates` option. + +.. _fa: +.. _Jinja2: https://jinja.palletsprojects.com/ + +.. _font-awesome: + +Font awesome +------------ + +ABlog templates will use of `Font Awesome`_ icons if one of the following is set: + +.. _Font Awesome: https://fontawesome.com/ + +.. confval:: fontawesome_link_cdn + + URL to `Font Awesome`_ :file:`.css` hosted at `Bootstrap CDN`_ or anywhere else. + Default: ``None`` + + .. _Bootstrap CDN: https://www.bootstrapcdn.com/fontawesome/ + +.. update:: Jul 29, 2015 + + :confval:`fontawesome_link_cdn` was a *boolean* option, and now became a *string* to enable using desired version of `Font Awesome`_. + To get the old behavior, use ``‘https://netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.min.css'``. + +.. confval:: fontawesome_included + + Sphinx_ theme already links to `Font Awesome`_. + Default: ``False`` + +Alternatively, you can provide the path to `Font Awesome`_ :file:`.css` with the following configuration option: + +.. confval:: fontawesome_css_file + + Path to `Font Awesome`_ :file:`.css` (default is ``None``) that will be linked to in HTML output by ABlog. + +.. _disqus-integration: + +Disqus integration +------------------ + +Of course one cannot think of a blog that doesn't allow for visitors to comment. +You can enable Disqus_ by setting :confval:`disqus_shortname` and :confval:`blog_baseurl` variables. +The reason for requiring :confval:`blog_baseurl` to be specified as of v0.7.2 is to ensure that Disqus associates correct URLs with threads when you serve new posts locally for the first time. + +.. confval:: disqus_shortname + + Disqus_ short name for the website. + +.. confval:: disqus_pages + + Choose to disqus pages that are not posts, default is ``False``. + +.. confval:: disqus_drafts + + Choose to disqus posts that are drafts (without a published date), default is ``False``. + +Isso integration +---------------- + +An alternative to Disqus, is `Isso <https://isso-comments.de/>`__. +Integration is provided by `sphinxnotes-isso`_ and the instructions there. + +.. _sphinxnotes-isso: https://sphinx-notes.github.io/isso/ + +Command Options +--------------- + +.. update:: Apr 7, 2015 + + Added :ref:`commands` options. + +.. confval:: ablog_website + + Directory name for build output files. Default is ``_website``. + +.. confval:: ablog_doctrees + + Directory name for build cache files. Default is ``.doctrees``. + +.. confval:: ablog_builder + + HTML builder, default is ``dirhtml``. Build HTML pages, but with a single directory per document. + Makes for prettier URLs (no .html) if served from a webserver. Alternative is ``html`` to build one HTML file per document. + +.. confval:: github_pages + + GitHub user name used by ``ablog deploy`` command. + See :ref:`deploy` and :ref:`deploy-to-github-pages` for more information. diff --git a/docs/manual/ablog-i18n.rst b/docs/manual/ablog-i18n.rst new file mode 100644 index 0000000..602a044 --- /dev/null +++ b/docs/manual/ablog-i18n.rst @@ -0,0 +1,56 @@ +ABlog Internationalization +========================== + +.. post:: Aug 30, 2014 + :tags: i18n + :category: Manual + :author: Luc, Ahmet + :language: Chinese + +ABlog automatically generates certain labels like :ref:`blog-posts` and :ref:`blog-categories`. +If these labels appear in English on your blog although you specified another language, then this page is for you. + +ABlog needs your help for translation of these labels. +Translation process involves the following steps: + +* Update translatable messages: + + Execute extract_messages_ each time a translatable message text is changed or added:: + + $ python setup.py extract_messages -o ablog/locales/sphinx.pot + ... + + This will create or update :file:`ablog/locales/sphinx.pot` file, the central messages catalog used by the different translations. + +Either: + +* Create new translation catalog: + + Execute init_catalog_ once for each *new* language, e.g.:: + + $ python setup.py init_catalog -l de -i ablog/locales/sphinx.pot -o ablog/locales/de/LC_MESSAGES/sphinx.po + + This will create a file :file:`ablog/locales/de/LC_MESSAGES/sphinx.po` in which translations needs to be placed. + +* Update translation catalog: + + Execute update_catalog_ for each *existing* language, e.g.:: + + $ python setup.py update_catalog -l de -i ablog/locales/sphinx.pot -o ablog/locales/de/LC_MESSAGES/sphinx.po + + This will update file :file:`ablog/locales/de/LC_MESSAGES/sphinx.po` where translations of new text needs to be placed. + +Finally: + +* Compile catalogs: + + Execute compile_catalog_ for each existing language, e.g:: + + $ python setup.py compile_catalog --directory ablog/locales/ --domain sphinx --locale de + + If you remove ``--locale de`` then all catalogs will be compiled. + +.. _extract_messages: https://babel.pocoo.org/en/latest/setup.html#extract-messages +.. _init_catalog: https://babel.pocoo.org/en/latest/setup.html#init-catalog +.. _update_catalog: https://babel.pocoo.org/en/latest/setup.html#update-catalog +.. _compile_catalog: https://babel.pocoo.org/en/latest/setup.html#compile-catalog diff --git a/docs/manual/ablog-quick-start.rst b/docs/manual/ablog-quick-start.rst new file mode 100644 index 0000000..128bb59 --- /dev/null +++ b/docs/manual/ablog-quick-start.rst @@ -0,0 +1,126 @@ +.. _quick-start: + + +ABlog Quick Start +================= + +.. post:: Mar 1, 2015 + :tags: config, tips + :author: Mehmet, Ahmet + :category: Manual + :location: SF + +This short walk through of blogging work flow assumes that you have already installed ABlog. If not, see :ref:`installation` guide. + +*Note that this post is a working draft. Feel free to revise it on GitHub.* + +Start a Project +--------------- + +To start a new project, run ``ablog start`` command in a directory where you want to keep your project source files. +This command will ask you a few questions and create the following files: + + * :file:`conf.py` that contains project configuration for building HTML pages. + + * :file:`first-post.rst`, a blog post example. + + * :file:`index.rst` that contains content for the *landing* page of your website. + + * :file:`about.rst`, another non-post page example. + + +Build and View +-------------- + +With no further delay, let's see what your project will look like. +First run ``ablog build``, in your project folder, to have HTML pages built in :file:`_website` folder. +Then, call ``ablog serve`` to view them in your default web browser. +See :ref:`commands` for more information about these commands. + +Your landing page is built from :file:`index.rst` and contains links to your first post and about page. +Take a look at :file:`index.rst` for some tips on navigation links within the project. + +Write Content +------------- + +If you are new to Sphinx_ and reStructuredText markup language, you might find `reStructuredText Primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__ useful. + +Pages +^^^^^ + +Pages in your project are :file:`.rst` files that are only a :rst:dir:`post` directive short of becoming blog posts. +To make regular pages accessible from the navigation bar, you need to list them in a :rst:dir:`toctree`. +This is shown for *about* page into :file:`index.rst`. + +Posts +^^^^^ + +You can convert any page to a post with a :rst:dir:`post` directive. +ABlog will take care of listing posts in specified archives and sidebars. + +Blog posts +^^^^^^^^^^ + +You can start new blog posts with either a front-matter or a directive using ABlog. +Simply use something based on the following template as the front-matter:: + +:blogpost: true +:date: January 1, 2020 +:author: A. Author +:location: World +:category: Blog +:language: English +:tags: blog + +Simply use something based on the following template as the directive for ABlog:: + + .. post:: January 1, 2020 + + :author: A. Author + :location: World + :category: Blog + :language: English + :tags: blog + +For more information, see :ref:`posting-directive` and :ref:`posting-front-matter`. + +Comments +-------- + +You can enable comments in your website by creating a Disqus_ account and obtaining a unique identifier, i.e. :confval:`disqus_shortname`. +See :ref:`disqus-integration` for configuration options. + +Analytics +--------- + +ABlog uses Alabaster_ theme by default. You can use theme options to set your `Google Analytics`__ identifier to enable tracking. + +__ https://www.google.com/analytics/ + +Configuration +------------- + +There are four major groups of configuration options that can help you customize how your website looks: + + * :ref:`config` - add blog authors, post locations and languages to your blog, adjust archive and feed content, etc. + + * `General configuration <https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration>`__ and `project information <https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information>`__ + + * :ref:`html-options` - configure appearance of your website. + + * Alabaster_ theme options - link to your GitHub account and project, set up tracking, etc. + +Other Folders +------------- + +You might have noticed that your project contains three folders that we have not mention yet. +Here they are: + + * :file:`_static` is for keeping image, :file:`.js`, and :file:`.css` files. + :confval:`html_static_path` Sphinx option for more information. + + * :file:`_templates` is for custom HTML templates. + See :confval:`templates_path` for more information. + + * :file:`.doctree` folder, created after build command is called, is where Sphinx_ stores the state of your project. + Files in this folder saves time when you rebuild your project. diff --git a/docs/manual/api.rst b/docs/manual/api.rst new file mode 100644 index 0000000..9704c3c --- /dev/null +++ b/docs/manual/api.rst @@ -0,0 +1,20 @@ +.. api: + +ABlog API +========= + +.. post:: Feb 17, 2018 + :tags: api + :author: Nabil Freij + :category: Manual + :location: World + +.. automodapi:: ablog + +.. automodapi:: ablog.blog + +.. automodapi:: ablog.commands + +.. automodapi:: ablog.post + +.. automodapi:: ablog.start diff --git a/docs/manual/cross-referencing-blog-pages.rst b/docs/manual/cross-referencing-blog-pages.rst new file mode 100644 index 0000000..bd4b86b --- /dev/null +++ b/docs/manual/cross-referencing-blog-pages.rst @@ -0,0 +1,47 @@ +Cross-referencing Blog Pages +============================ + +.. post:: May 11, 2014 + :tags: tips, Sphinx + :category: Manual + :location: Pittsburgh + :author: Ahmet + +ABlog creates references to all post and archive pages. +Posts can be cross-referenced using the name of the file, or when the file is named :file:`index`, the name of the folder that contains the file. + +This page, :ref:`cross-referencing-blog-pages`, for example is referenced as ``:ref:`cross-referencing-blog-pages``` using :rst:role:`ref` role. + +When posts have long file names, it may be inconvenient to use them repeatedly for cross-referencing. +An alternative that Sphinx_ offers is creating your own short and unique labels for cross-referencing to posts. See :ref:`xref-syntax` for details. + +.. _archives: + +Archive pages +------------- + +Archive pages, on the other hand, can be cross-referenced by combining archive type and archive name as follows: + +============== ========================== =============================== +Archive Example reStructured Text +============== ========================== =============================== +Posts :ref:`blog-posts` ``:ref:`blog-posts``` +Drafts :ref:`blog-drafts` ``:ref:`blog-drafts``` +Blog Feed :ref:`blog-feed` ``:ref:`blog-feed``` +Author :ref:`author-ahmet` ``:ref:`author-ahmet``` +Language :ref:`language-en` ``:ref:`language-en``` +Location :ref:`location-pittsburgh` ``:ref:`location-pittsburgh``` +============== ========================== =============================== + +Following archive pages list all posts by grouping them: + +============== ========================== =============================== +Archive Example reStructured Text +============== ========================== =============================== +By tag :ref:`blog-tags` ``:ref:`blog-tags``` +By author :ref:`blog-authors` ``:ref:`blog-authors``` +By language :ref:`blog-languages` ``:ref:`blog-languages``` +By location :ref:`blog-locations` ``:ref:`blog-locations``` +By category :ref:`blog-categories` ``:ref:`blog-categories``` +By archive :ref:`blog-archives` ``:ref:`blog-archives``` +============== ========================== =============================== diff --git a/docs/manual/deploy-to-github-pages.rst b/docs/manual/deploy-to-github-pages.rst new file mode 100644 index 0000000..c98da9a --- /dev/null +++ b/docs/manual/deploy-to-github-pages.rst @@ -0,0 +1,41 @@ + +Deploy to GitHub Pages +====================== + + +.. post:: Apr 07, 2015 + :tags: deploy + :author: Ahmet + :category: Manual + :location: SF + +If you are looking for a place to publish your blog, `GitHub Pages`__ might be the place for you. + +__ https://pages.github.com/ + +Assuming that you have a GitHub account, here are what you need to do to get published: + +1. Head over to GitHub_ and create a new repository named ``username.github.io``, where username is your username (or organization name) on GitHub. + +2. (optional) If you followed the link, you might as well give a star to ABlog ;) + +3. Set :confval:`github_pages` configuration variable in :file:`conf.py` file. + +4. Run ``ablog build`` in your project folder. + +5. Run ``ablog deploy``. This command will + + i. clone your GitHub pages repository to project folder, + + ii. copy all files from build folder (:file:`_website`) to :file:`username.github.io`, + + iii. add and commit copied files, + + iv. add `.nojekyll <https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#troubleshooting-publishing-from-a-branch>`_ + file, since this ain't no Jekyll_ + + v. and finally push the changes to publish. + +Let us know how this works for you! + +.. _Jekyll: https://jekyllrb.com/ diff --git a/docs/manual/external-post.rst b/docs/manual/external-post.rst new file mode 100644 index 0000000..9eb19ab --- /dev/null +++ b/docs/manual/external-post.rst @@ -0,0 +1,10 @@ +:blogpost: true +:date: September 01, 2021 +:author: Chris +:category: Manual +:external_link: https://www.sphinx-doc.org/en/master/ + +External post +============= + +This text will be in auto-generated post previews, but links to the post will direct to ``external_link``. diff --git a/docs/manual/forever-draft.rst b/docs/manual/forever-draft.rst new file mode 100644 index 0000000..7ef72d7 --- /dev/null +++ b/docs/manual/forever-draft.rst @@ -0,0 +1,33 @@ +Draft Example +============= + +.. post:: + :tags: draft + :category: Manual + + +As the title suggests, this is a draft example and shall remain so until the end of time or internet. + +How do you draft a post? +------------------------ + +Just indicate that the page is a post using :rst:dir:`post` directive, but do not provide give a published date: + +.. code-block:: rst + + .. post:: + :tags: draft + :category: Manual + +You can still label a post you are drafting with tags and categories, but the post will not be listed in corresponding archive pages until it is published. + +How can you see a list of drafts? +--------------------------------- + +See :ref:`blog-drafts` archive page, which can be referred to as ``:ref:`blog-drafts```. + +Why would you make a post draft? +-------------------------------- + +Let's say you are using Disqus_ on your website, and allowing non-post pages to be discussed as well, but you don't want a draft to be discussed before it is published. +By adding :rst:dir:`post` directive without published date and keeping configuration variable :confval:`disqus_drafts` as ``False``, you can achieve that. diff --git a/docs/manual/images/notebook_cells.png b/docs/manual/images/notebook_cells.png Binary files differnew file mode 100644 index 0000000..1411a86 --- /dev/null +++ b/docs/manual/images/notebook_cells.png diff --git a/docs/manual/markdown.md b/docs/manual/markdown.md new file mode 100644 index 0000000..63a38aa --- /dev/null +++ b/docs/manual/markdown.md @@ -0,0 +1,56 @@ +--- +blogpost: true +date: Oct 10, 2020 +author: Nabil Freij +location: World +category: Manual +language: English +--- + +# Markdown Support + +ABlog can support markdown pages using [myst-parser](https://pypi.org/project/myst-parser/). +This page is a markdown file underneath. + +You will need to do a few things to get setup. + +1. Install [myst-parser](https://pypi.org/project/myst-parser/) +2. Add these options to your config, `conf.py` + +```python +extensions = [ + ... + "myst_parser", + ... +] +myst_update_mathjax = False +``` + +Then use the new blogpost metadata format (with a slight twist): + +``` +--- +blogpost: true +date: Oct 10, 2020 +author: Nabil Freij +location: World +category: Manual +language: English +--- +``` + +Notice here we do not have a ":" at the start since the markdown metadata format is different from rst. + +Please be aware that adding "myst-parser" will mean it will read all markdown files and try to parse them. +You will need to use the following in your `conf.py` to prevent this: + +```python +exclude_patterns = [ + "posts/*/.ipynb_checkpoints/*", + ".github/*", + ".history", + "github_submodule/*", + "LICENSE.md", + "README.md", +] +``` diff --git a/docs/manual/notebook_support.ipynb b/docs/manual/notebook_support.ipynb new file mode 100644 index 0000000..0a5b023 --- /dev/null +++ b/docs/manual/notebook_support.ipynb @@ -0,0 +1,81 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Jupyter Notebook Posting" + ] + }, + { + "cell_type": "raw", + "metadata": { + "raw_mimetype": "text/restructuredtext" + }, + "source": [ + ".. post:: 27 Oct 2018\n", + " :author: Nabil Freij, Second Author\n", + " :tags: posting\n", + " :category: Manual" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To add support for Notebooks to your Ablog instance, you need to configure your `docs/conf.py` (or wherever your `conf.py` is located.\n", + "\n", + "You will need to add\n", + "\n", + "```\n", + " extensions = [..., 'nbsphinx', ...]\n", + " exclude_patterns = ['docs/manual/.ipynb_checkpoints/*'] (To exclude the notebook autosaves)\n", + "```\n", + "\n", + "You will need to install [nbsphinx](https://nbsphinx.readthedocs.io/) either from `Anaconda` or `pip`. You might need to install [ipython](https://ipython.org/) to make sure the notebook can be run." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Within the notebook you need to make sure the cells are in this order: Titlte cell, post cell. So for this notebook, it looks like this: " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "So the information is similar to how you create a normal RST post." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Another working example is SunPy's website which runs [Ablog](https://sunpy.org/blog.html). The Pull Request that added support can be found [here](https://github.com/sunpy/sunpy.org/pull/131) and how to link them to a [Binder](https://mybinder.org/) instance [here](https://github.com/sunpy/sunpy.org/pull/134)." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.6.6" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/manual/post-excerpts-and-images.rst b/docs/manual/post-excerpts-and-images.rst new file mode 100644 index 0000000..68cd106 --- /dev/null +++ b/docs/manual/post-excerpts-and-images.rst @@ -0,0 +1,44 @@ +Post Excerpts and Images +======================== + +.. post:: May 12, 2014 + :tags: directive + :category: Manual + :location: Pittsburgh + :author: Ahmet + :exclude: + :image: 2 + + This post describes how to choose an excerpt and an image image for a post to be displayed in archive pages. + +Excerpts +-------- + +ABlog, by default, uses first paragraph of the document as post excerpt. +Default number of paragraphs to use in excerpts is controlled via :confval:`post_auto_excerpt` configuration variable. +This option can be overwritten using ``:excerpt:`` option in :rst:dir:`post` directive. + +Alternatively, you can provide some content in a post directive as follows:: + + .. post:: Apr 15, 2014 + + This is all of the excerpt for this post. + +This content is going to be used as excerpt in archive pages. +Furthermore, if you do not want the excerpt to be included in the post, you can use ``:exclude:`` option as follows:: + + .. post:: Apr 15, 2014 + :exclude: + + This is all of the excerpt for this post. + It will be displayed in archive pages and excluded from the post page. + +Images +------ + +Let's first include a local and a non-local image in this post. + +.. image:: /_static/ablog.png +.. image:: https://www.python.org/static/community_logos/python-logo.png + +To link the second one of these, we add ``:image: 2`` option in :rst:dir:`post` directive. diff --git a/docs/manual/posting-and-listing.rst b/docs/manual/posting-and-listing.rst new file mode 100644 index 0000000..1ae9a0f --- /dev/null +++ b/docs/manual/posting-and-listing.rst @@ -0,0 +1,212 @@ +Posting and Listing +=================== + +.. post:: May 9, 2014 + :tags: directive + :category: Manual + :location: Pittsburgh + :author: Ahmet + +This post describes :rst:dir:`post`, :rst:dir:`update`, and :rst:dir:`postlist` directives. + +.. _posting-directive: + +Posting with a Directive +------------------------ + +Any page in a Sphinx_ project can be converted to a post using the following directive: + +.. rst:directive:: post + + All possible directive options are shown below:: + + .. post:: 15 Apr, 2013 + :tags: tips, ablog, directive + :category: Example, How To + :author: Ahmet, Durden + :location: Pittsburgh, SF + :redirect: blog/old-page-name-for-the-post + :excerpt: 2 + :image: 1 + :external_link: https://anexternalwebsite.org + :nocomments: + + **Drafts & Posts** + + Posts without dates or with future dates are considered as drafts and are published only in :ref:`blog-drafts` archive page. + + Posts with dates that are older than the day Sphinx project is built are published in :ref:`blog-posts` page. + + Post date format must follow the format specified with confval:`post_date_format` configuration option. + + **Tags & Categories** + + You can specify multiple tags and categories by separating them with commas. + Posts will be listed in archive pages generated for each unique tag and category. + + **Authors, Languages, & Locations** + + Likewise, you can specify authors, languages, and locations of a post using ``:author:``, ``:language:``, and ``:location:`` options. + All of these option names are in their singular form, but multiple values separated by commas are accepted. + + Using :confval:`blog_authors`, :confval:`blog_languages`, and :confval:`blog_locations` configuration variables, you can also provide home pages and/or full display names of authors, languages, and locations, which will be displayed in archive pages generated for all unique authors, languages, and locations. + + **Redirections** + + You can make ABlog create pages that will redirect to current post using ``:redirect:`` option. It takes a comma separated list of paths, relative to the root folder. + The redirect page waits for :confval:`post_redirect_refresh` seconds before redirection occurs. + + **Disable comments** + + You can disable comments for the current post using the ``:nocomments:`` option. + Currently there is no way to disable comments in a specific page. + + **Excerpts & Images** + + By default, ABlog uses the first paragraph of a page as post excerpt. + You can change this behavior and also add an image to the excerpt. + To find out how, see :ref:`post-excerpts-and-images`. + + **Canonical links** + + If you re-publish content already existing on another URL (e.g., if you re-publish content from an employer's blog your personal one), use the ``canonical_link`` parameter to create a [canonical link relation](https://datatracker.ietf.org/doc/html/rfc6596) to the original version. + + **External links** + + If you'd like a post to point to an external website (e.g., if you host your posts on a blogging platform like Medium but wish to maintain a list of posts on your ``Ablog`` site), use the ``external_link`` parameter and this will be used instead. + + **Update Notes** + + .. rst:directive:: update + + Update in a post can be noted anywhere in the post as follows:: + + .. update:: 20 Apr, 2014 + + Added :rst:dir:`update` directive and :ref:`posting-sections` section. + Also revised the text here and there. + + Update date format must follow the format specified with :confval:`post_date_format` configuration option. + + Update directive renders like the updates that are at the end of this post. + +.. _posting-front-matter: + +Posting with page front-matter +------------------------------ + +If you'd prefer to use `page front matter <https://www.sphinx-doc.org/en/1.7/markup/misc.html>`__ instead of using a directive, you may mark a page as a "blog post" by adding the following front-matter at the top: + +.. code-block:: rst + + :blogpost: true + +``ABlog`` will treat any pages with this front-matter as a blog post. +All fields that are available to the :ref:`posting directive <posting-directive>` can be given as page-level front-matter as well. + +.. admonition:: Automatically detect blog posts with a ``glob`` pattern + :class: tip + + Instead of adding ``blogpost: true`` to each page, you may also provide a pattern (or list of patterns) in your ``conf.py`` file using the ``blog_post_pattern`` option. + Any filenames that match this pattern will be treated as blog posts (and page front-matter will be used to classify the blog post). + For example, the following configuration would match all ``rst`` files in the ``posts/`` folder: + + .. code-block:: python + + blog_post_pattern = "posts/*.rst" + + and this configuration will match all blog posts that match either ``rst`` or ``md``: + + .. code-block:: python + + blog_post_pattern = ["posts/*.rst", "posts/*.md"] + +.. _posting-sections: + +Posting Sections +---------------- + +.. post:: Aug 20, 2014 + :tags: directive + :category: Manual + :location: SF + :author: Ahmet + +:rst:dir:`post` directive can be used multiple times in a single page to create multiple posts of different sections of the document. + +When :rst:dir:`post` is used more than once, post titles and excerpts are extracted from the sections that contain the directives. +This behavior can also be set as the default behavior using :confval:`post_always_section` configuration options. + +Some caveats and differences from posting a document once are: + + * Next and previous links at the bottom will only regard the first post in the document. + * Information displayed on the sidebar will belong to the first post. + * References for section posts is not automatically created. Labels for cross-referencing needs to be created manually, e.g., ``.. _posting-sections``. See :ref:`xref-syntax` for details. + +Multiple use of :rst:dir:`post` may be suitable for major additions to a previous post. For minor changes, :rst:dir:`update` directive may be preferred. + +Listing +------- + +A list of posts can be displayed in any page using the following directive: + +.. rst:directive:: postlist + + Following example display all the options the directive takes:: + + .. postlist:: 5 + :author: Ahmet + :category: Manual + :location: Pittsburgh + :language: en + :tags: tips + :date: %A, %B %d, %Y + :format: {title} by {author} on {date} + :list-style: circle + :excerpts: + :sort: + :expand: Read more ... + + This will result in a bullet list of up to 5 posts (default is all) authored by `:ref:`author-ahmet`` in `:ref:`language-en`` when he was in `:ref:`location-pittsburgh`` and posted in `:ref:`category-manual`` with tags `:ref:`tag-tips``. + Posts will be in ``:sort:``\ed to appear in chronological order and listed with their ``:excerpts:``. + Here are those posts: + + .. postlist:: 5 + :author: Ahmet + :category: Manual + :location: Pittsburgh + :language: en + :tags: tips + :date: %A, %B %d, %Y + :format: {title} by {author} on {date} + :list-style: circle + :excerpts: + :sort: + :expand: Read more ... + + When no options are given all posts will be considered and they will be ordered by recency. + Also, note that if the current post is one of the most recent posts, it will be omitted. + +.. update:: Aug 21, 2014 + + Added :rst:dir:`update` directive and + :ref:`posting-sections` section. + Also revised the text here and there. + +.. update:: Sep 15, 2014 + + * :rst:dir:`post` directive has ``:language:`` option. + * :rst:dir:`postlist` directive takes arguments to filter posts. + +.. update:: Mar 28, 2015 + + Added ``:excerpts:`` option to :rst:dir:`postlist` to list posts with their excerpts. + +.. update:: Apr 14, 2015 + + Added ``:list-style:`` option to :rst:dir:`postlist` to control bullet list style. + *circle*, *disc*, and *none* (default) are recognized. + +.. update:: May 25, 2021 + + Added ``:expand:`` option to :rst:dir:`postlist` to add a call to action to continue reading the post. diff --git a/docs/manual/templates-themes.rst b/docs/manual/templates-themes.rst new file mode 100644 index 0000000..1b0fbcd --- /dev/null +++ b/docs/manual/templates-themes.rst @@ -0,0 +1,101 @@ +Templating and Themes Support +============================= + +.. post:: Oct 26, 2024 + :tags: themes + :category: Manual + :author: Libor + +Ablog, being a Sphinx extension, has highly customizable HTML output. The generated HTML files are based on `Sphinx templates`_. You, or Sphinx themes, can partially or completely override these templates to customize the resulting HTML. + +.. _Sphinx templates: https://www.sphinx-doc.org/en/master/development/html_themes/templating.html + +.. versionchanged:: 0.11 + The :doc:`Ablog 0.11 </release/ablog-v0.11-released>` has changed and improved the way you can customize templates and themes. Please note that this document describes the new way of customizing templates and themes support. + +.. _sidebars: + +Blog sidebars +------------- + +Sidebars are a common way to provide additional information to the reader. There are seven Ablog sidebars you can include in your HTML output using the Sphinx_ :confval:`html_sidebars` configuration option (in addition to your theme sidebars). + +- ``ablog/postcard.html`` provides information regarding the current post (when on a post page). +- ``ablog/recentposts.html`` lists the most recent five posts. +- ``ablog/tagcloud.html`` provides links to archive pages generated for each tag. +- ``ablog/category.html``, ``ablog/authors.html``, ``ablog/languages.html``, and ``ablog/locations.html`` sidebars generate lists of links to respective archive pages with the number of matching posts (e.g., "Manual (14)", "2023 (8)", "English (22)"). + +For example, the sidebars that you see on this website on the left are: + +.. code-block:: python + + html_sidebars = { + "**": [ + # Comes from Alabaster theme + "about.html", + "searchfield.html", + # Ablog sidebars + "ablog/postcard.html", + "ablog/recentposts.html", + "ablog/tagcloud.html", + "ablog/categories.html", + "ablog/archives.html", + "ablog/authors.html", + "ablog/languages.html", + "ablog/locations.html", + ] + } + +Styling default Ablog sidebars +------------------------------ + +Ablog standard sidebars are wrapped in ``<div>`` with CSS classes like :samp:`ablog-sidebar-item ablog__{<template_name>}`, making them easier to style. + +For example, the ``recentposts.html`` template is wrapped in ``<div class="ablog-sidebar-item ablog__recentposts">``. + +.. seealso:: + + Built-in sidebars can be found in the ``ablog/`` folder in the `Ablog source code <https://github.com/sunpy/ablog/tree/main/src/ablog/templates/ablog>`_. + +If styling is not enough, you can override the Ablog templates in your Sphinx project or in the Sphinx theme. + +Partial or complete override of Ablog templates +----------------------------------------------- + +To control whether Ablog injects its own templates into the Sphinx build, you can use the following ``conf.py`` configuration option: + +.. confval:: skip_injecting_base_ablog_templates + + If set to ``True``, Ablog will not inject its own templates into the Sphinx build. This is useful if you want to completely override Ablog templates in your Sphinx project or in the Sphinx theme. The default is ``False``. + +Customizing templates in the project +------------------------------------ + +All Ablog templates are under the ``ablog/`` folder space. For example, ``ablog/postcard.html``. You can override these templates by placing them in the ``ablog/`` folder in your project templates folder. + +#. Add the :confval:`templates_path` option in your ``conf.py`` file: + + .. code-block:: python + + templates_path = ["_templates"] + +#. Create a folder ``_templates/`` next to your ``conf.py`` file. It will hold your custom templates. +#. Create a folder ``ablog/`` inside the ``_templates/`` folder. +#. Create a file here with the same name as the template you want to override. For example, ``postcard.html``. This file will be used as a custom template for the sidebar. You can copy the content of the original template from the Ablog source code and modify it as you need. +#. Optionally: if you want to completely override all Ablog templates, set the :confval:`skip_injecting_base_ablog_templates` option to ``True``, copy all Ablog templates here, and customize them as you need. + +Customizing templates in the theme +---------------------------------- + +If you are a Sphinx theme author, you can ship customized Ablog templates in your theme. You can override Ablog templates by placing them in the ``ablog/`` folder in your theme templates, e.g., ``ablog/postcard.html``. + +#. In the theme root (where the ``theme.toml`` (or ``theme.ini`` in older Sphinx themes) file is), create a folder ``ablog/``. +#. Create a file here with the same name as the template you want to override. For example, ``postcard.html``. +#. This file will be used as a custom template for the sidebar. You can copy the content of the original template from the Ablog source code and modify it as you need. +#. In your ``theme.toml`` file, add the following (under the ``[options]`` section): + + .. code-block:: toml + + ablog_inject_templates_after_theme = true + + This will ensure that Ablog templates are injected *after* the theme templates, so you can override them while still using the Ablog templates as a fallback. diff --git a/docs/manual/watch-yourself-blogging.rst b/docs/manual/watch-yourself-blogging.rst new file mode 100644 index 0000000..84da97b --- /dev/null +++ b/docs/manual/watch-yourself-blogging.rst @@ -0,0 +1,21 @@ + +Watch Yourself Blogging +======================= + +.. post:: Apr 19, 2015 + :tags: commands, tips + :category: Manual + :author: Ahmet + :location: SF + :language: en + +Wouldn't you like your blog being rebuilt and served to you automatically as you are blogging on a sunny Sunday afternoon? +It's now possible with the improved ``ablog serve`` command. + +First, you need to install Watchdog_ Python package, e.g. `pip install watchdog`. +Then, you need to run ``ablog serve -r``. +Regardless of the weather being sunny or the day of the week, your project will be rebuilt when you change a page or add a new one. +This won't refresh your browser page though. +Unless you want to hit refresh once in a while, you can easily find an auto refresher extension for you browser. + +.. _Watchdog: https://github.com/gorakhargosh/watchdog diff --git a/docs/nitpick-exceptions b/docs/nitpick-exceptions new file mode 100644 index 0000000..c1c9092 --- /dev/null +++ b/docs/nitpick-exceptions @@ -0,0 +1,8 @@ +py:class docutils.nodes.Node +py:class docutils.nodes.General +py:class docutils.nodes.Body +py:class docutils.nodes.admonition +py:class docutils.parsers.rst.directives.admonitions.BaseAdmonition +py:class docutils.transforms.Transform +py:class docutils.nodes.Element +py:class docutils.nodes.Admonition diff --git a/docs/release/ablog-v0.1-released.rst b/docs/release/ablog-v0.1-released.rst new file mode 100644 index 0000000..37af594 --- /dev/null +++ b/docs/release/ablog-v0.1-released.rst @@ -0,0 +1,20 @@ +:blogpost: true +:tags: tips +:author: Ahmet +:category: Release +:location: SF +:date: May 14, 2014 + +ABlog v0.1 released +=================== + +ABlog v0.1 is released. + +This is the very first release, so there are no release notes in this post. + +Yes, this page is also a post and it resides in a folder different from +most other posts in this blogumentation. + +The idea is to enable making any page in a Sphinx_ project a post so that +users of a software package can subscribe to feeds and follow new releases +as well as code examples added to the documentation. diff --git a/docs/release/ablog-v0.10-released.rst b/docs/release/ablog-v0.10-released.rst new file mode 100644 index 0000000..1609520 --- /dev/null +++ b/docs/release/ablog-v0.10-released.rst @@ -0,0 +1,282 @@ +ABlog v0.10 released +==================== + +.. post:: Nov 17, 2019 + :author: Nabil Freij + :category: Release + :location: World + +ABlog v0.10 is released with the main focus being to support the latest version of Sphinx as well as Python 3 only support. + +Ablog V0.9.X will no longer be supported as Python 2 comes to an end in a few months and it is time people upgraded. + +Pull Requests merged in: + +`Overhaul of package underneath for python3 only <https://github.com/sunpy/ablog/pull/41>`__ from `nabobalis <https://github.com/nabobalis>`__. + +`Add validation for conf.py entries <https://github.com/sunpy/ablog/pull/38>`__ from `rayalan <https://github.com/rayalan>`__. + +`Deploy improve <https://github.com/sunpy/ablog/pull/42>`__ from `rayalan <https://github.com/rayalan>`__. + +`Get ablog ready for 0.10 <https://github.com/sunpy/ablog/pull/46>`__ from `nabobalis <https://github.com/nabobalis>`__. + +ABlog v0.10.1 released +---------------------- + +Pull Requests merged in: + +`Change StopIteration to return <https://github.com/sunpy/ablog/pull/48>`__ from `remyabel2 <https://github.com/remyabel2>`__. + +ABlog v0.10.2 released +---------------------- + +Pull Requests merged in: + +`Fix unclosed span tag <https://github.com/sunpy/ablog/pull/41>`__ from `ykrods <https://github.com/ykrods>`__. + +ABlog v0.10.3 released +---------------------- + +Pull Requests merged in: + +`Pin werkzeug to < 1 <https://github.com/sunpy/ablog/pull/53>`__ from `dstansby <https://github.com/dstansby>`__. + +`MNT: Fix Giles URL <https://github.com/sunpy/ablog/pull/50>`__ from `pllim <https://github.com/pllim>`__. + +ABlog v0.10.4 released +---------------------- + +Pull Requests merged in: + +`Add zh_CN locale <https://github.com/sunpy/ablog/pull/61>`__ from `daimon99 <https://github.com/daimon99>`__. + +`Add intersphinx to the extension list <https://github.com/sunpy/ablog/pull/60>`__ from `plaindocs <https://github.com/plaindocs>`__. + +`Fix "test5" <https://github.com/sunpy/ablog/pull/58>`__ and `Use "dirhtml" builder on Read The Docs <https://github.com/sunpy/ablog/pull/57>`__ from `blueyed <https://github.com/blueyed>`__. + +ABlog v0.10.5 released +---------------------- + +Pull Requests merged in: + +`Add custom GitHub URL support <https://github.com/sunpy/ablog/pull/63>`__ from `tg-m <https://github.com/tg-m>`__. + +ABlog v0.10.6 released +---------------------- + +Pull Requests merged in: + +`Add french locale <https://github.com/sunpy/ablog/pull/65>`__ from `kujiu <https://github.com/kujiu>`__. + +ABlog v0.10.7 released +---------------------- + +Pull Requests merged in: + +`Automatically add templates path to documentation <https://github.com/sunpy/ablog/pull/63>`__ from `choldgraf <https://github.com/choldgraf>`__. + +ABlog v0.10.8 released +---------------------- + +Removed the hard dependencies on alabaster and sphinx-automodapi. + +Replaced `werkzeug <https://pypi.org/project/Werkzeug/>`__ with `feedgen <https://pypi.org/project/feedgen/>`__ due to the former removing ATOM support. + +Version pin of nbsphinx has been removed. + +ABlog v0.10.9 released +---------------------- + +Pull Requests merged in: + +`frontmatter and blog post matching <https://github.com/sunpy/ablog/pull/63>`__ from `choldgraf <https://github.com/choldgraf>`__. + +ABlog v0.10.10 released +----------------------- + +Pull Requests merged in: + +`Various Issues <https://github.com/sunpy/ablog/pull/77>`__. + +`Fix missing reference caused by ref with title <https://github.com/sunpy/ablog/pull/73>`__ from `ykrods <https://github.com/ykrods>`__. + +`Add instructions for starting new blog posts with front-matter <https://github.com/sunpy/ablog/pull/71>`__ from `kakirastern <https://github.com/kakirastern>`__. + +ABlog v0.10.11 released +----------------------- + +Pull Requests merged in: + +`improving glob matching and documenting it <https://github.com/sunpy/ablog/pull/79>`__ from `choldgraf <https://github.com/choldgraf>`__. + + +ABlog v0.10.12 released +----------------------- + +Pull Requests merged in: + +`id of feed is now blog.blog_baseurl <https://github.com/sunpy/ablog/pull/83>`__. + +ABlog v0.10.13 released +----------------------- + +Pull Requests merged in: + +`updated CI and py39 tests <https://github.com/sunpy/ablog/pull/86>`__. +`Add test #87 <https://github.com/sunpy/ablog/pull/87>`__. +`Some minor fixes <https://github.com/sunpy/ablog/pull/88>`__. +`Ensure blog_post_pattern are relative to srcdir <https://github.com/sunpy/ablog/pull/89>`__. + +ABlog v0.10.14 released +----------------------- + +Pull Requests merged in: + +`feat(feeds): Add missing Atom entry metadata <https://github.com/sunpy/ablog/pull/92>`__. +`feat(feeds): Add entry element template support <https://github.com/sunpy/ablog/pull/93>`__. +`misc update <https://github.com/sunpy/ablog/pull/94>`__. + + +ABlog v0.10.15 released +----------------------- + +Fixed `Index Out of Range with Atom Feeds <https://github.com/sunpy/ablog/issues/96>`__. + +ABlog v0.10.16 released +----------------------- + +Pull Requests merged in: + +`fix(feeds): Feed validation, templates regression <https://github.com/sunpy/ablog/pull/97>`__. + +ABlog v0.10.17 released +----------------------- + +Pull Requests merged in: + +`Correct draft URL <https://github.com/sunpy/ablog/pull/98>`__. + +ABlog v0.10.18 released +----------------------- + +Pull Requests merged in: + +`Correct posts URL <https://github.com/sunpy/ablog/pull/99>`__. +`Add isso integration <https://github.com/sunpy/ablog/pull/100>`__. + +ABlog v0.10.19 released +----------------------- + +Pull Requests merged in: + +`Add expand option <https://github.com/sunpy/ablog/pull/104>`__. + + +ABlog v0.10.20 released +----------------------- + +Pull Requests merged in: + +`fix documentation typo in blog-drafts <https://github.com/sunpy/ablog/pull/105>`__. +`Fix typo <https://github.com/sunpy/ablog/pull/109>`__. +`Catalan translation <https://github.com/sunpy/ablog/pull/113>`__. +`Fix ablog post <https://github.com/sunpy/ablog/pull/114>`__. + +ABlog v0.10.21 released +----------------------- + +Pull Requests merged in: + +`Fix/multilang feed links <https://github.com/sunpy/ablog/pull/116>`__. + +BREAKING CHANGE - DROPPED PYTHON 3.6 SUPPORT + +ABlog v0.10.22 released +----------------------- + +Pull Requests merged in: + +`Fix tags field for myst_parser <https://github.com/sunpy/ablog/pull/119>`__. + +ABlog v0.10.23 released +----------------------- + +Pull Requests merged in: + +`optionally show previous / next links on post page <https://github.com/sunpy/ablog/pull/120>`__. +`add classes to post elements <https://github.com/sunpy/ablog/pull/121>`__. + + +ABlog v0.10.24 released +----------------------- + +Breaking Changes: + +Minimum versions of packages increased: + +.. code-block:: bash + + feedgen>=0.9.0 + invoke>=1.6.0 + python-dateutil>=2.8.0 + sphinx>=4.0.0 + watchdog>=2.0.0 + myst-parser>=0.17.0 + pytest>=6.0.0 + +Pull Requests merged in: + +`Get rid of eval and fix #128 <https://github.com/sunpy/ablog/pull/131>`__. +`CI Tweak <https://github.com/sunpy/ablog/pull/132>`__. + +ABlog v0.10.25 released +----------------------- + +Pull Requests merged in: + +`Normalise path to posix as sphinx expects <https://github.com/sunpy/ablog/pull/134>`__. + +ABlog v0.10.26 released +----------------------- + +Pull Requests merged in: + +`docs: Fix format of sphinx.ext.extlink for Sphinx 5.x <https://github.com/sunpy/ablog/pull/141>`__. +`docs: Use ref link rather than hardcode link <https://github.com/sunpy/ablog/pull/140>`__. +`Ci and Warnings Fix <https://github.com/sunpy/ablog/pull/142>`__. + +ABlog v0.10.27 released +----------------------- + +Pull Requests merged in: + +`Improve conditional check for author metadata <https://github.com/sunpy/ablog/pull/146>`__. + +ABlog v0.10.28 released +----------------------- + +Pull Requests merged in: + +`findall -> traverse for older versions of docutils <https://github.com/sunpy/ablog/pull/152>`__. + +ABlog v0.10.29 released +----------------------- + +Pull Requests merged in: + +`Fix the error on some empty option value of post directive <https://github.com/sunpy/ablog/pull/155>`__. + +ABlog v0.10.30 released +----------------------- + +Pull Requests merged in: + +`Sort Feed posts by date <https://github.com/sunpy/ablog/pull/172>`__. +`Fix sidebars ablog translations <https://github.com/sunpy/ablog/pull/161>`__. + +ABlog v0.10.31 released +----------------------- + +Pull Requests merged in: + +`Add external links for posts <https://github.com/sunpy/ablog/pull/112>`__. diff --git a/docs/release/ablog-v0.11-released.rst b/docs/release/ablog-v0.11-released.rst new file mode 100644 index 0000000..9936afd --- /dev/null +++ b/docs/release/ablog-v0.11-released.rst @@ -0,0 +1,128 @@ +ABlog v0.11 released +==================== + +.. post:: March 23, 2023 + :author: Nabil Freij + :category: Release + :location: World + +ABlog v0.11 is released with the main focus being to update and tweak the HTML templates allow themes to override the default templates. +In addition, all ablog elements in the templates wrapped in ``ablog__*`` divs to allow custom CSS rules. + +We also adopt `NEP29 <https://numpy.org/neps/nep-0029-deprecation_policy.html>`__ and drop support for older versions of Python and package versions that are 24 months old or older at time of release. + +Added support for external links to be posts. + +There are several breaking changes: + +- 1. The template files are now in the ``templates/ablog`` folder. + Older templates are still in the old location but will raise a warning. + These will be removed in a future version, please do not use them anymore. + You will need to update any paths to them to add "ablog/" to the path. +- 2. ``ablog`` has support for not injecting its own templates into the Sphinx build. + This is supported by add ``skip_injecting_base_ablog_templates = True`` to your configuration file. +- 3. Minimum version of Python is >=3.9 and Sphinx is >=5.0. + +Pull Requests merged in: + +`Template rework <https://github.com/sunpy/ablog/pull/144>`__. + +`Add external links for posts <https://github.com/sunpy/ablog/pull/112>`__ from `Chris Holdgraf <https://github.com/choldgraf>`__. + +Unreleased +---------- + +Pull Requests merged in: + +`Fix theme support for Ablog <https://github.com/sunpy/ablog/pull/295>`__ from `Libor Jelínek <https://github.com/liborjelinek/>`__. + +ABlog v0.11.1 released +---------------------- + +Pull Requests merged in: + +`Update version handling to remove use of pkg_resources <https://github.com/sunpy/ablog/pull/211>`__ + +ABlog v0.11.2 released +---------------------- + +Pull Requests merged in: + +`append posts to atom feed to keep post order from new to old <https://github.com/sunpy/ablog/pull/216>`__ from `lexming <https://github.com/lexming>`__. +`avoid spurious warning about posts with front-matter and post directive <https://github.com/sunpy/ablog/pull/214>`__ from `lexming <https://github.com/lexming>`__. + +ABlog v0.11.3 released +---------------------- + +Pull Requests merged in: + +`use fully qualified URLs for images in atom feed <https://github.com/sunpy/ablog/pull/218>`__ from `lexming <https://github.com/lexming>`__. + +ABlog v0.11.4 released +---------------------- + +Pull Requests merged in: + +`Use paragraph instead of container for blog post excerpts <https://github.com/sunpy/ablog/pull/226>`__ from `dstansby <https://github.com/dstansby>`__. + +ABlog v0.11.5 released +---------------------- + +Pull Requests merged in: + +`Fix incorrect /div when using discuss <https://github.com/sunpy/ablog/pull/251>`__ from `Cadair <https://github.com/Cadair>`__. + +ABlog v0.11.6 released +---------------------- + +Pull Requests merged in: + +`Adds IT locale <https://github.com/sunpy/ablog/pull/253>`__ from `Stefano David <https://github.com/stefanodavid>`__. + +`Enables configuring a canonical_link for individual posts <https://github.com/sunpy/ablog/pull/258>`__ from `Hendrik Makait <https://github.com/hendrikmakait>`__. + +ABlog v0.11.7 released +---------------------- + +Pull Requests merged in: + +`Add stylesheet for tagcloud <https://github.com/sunpy/ablog/pull/268>`__ from `Shengyu Zhang <https://github.com/SilverRainZ>`__. + +`Create demo/ before running ablog start <https://github.com/sunpy/ablog/pull/269>`__ from `Shengyu Zhang <https://github.com/SilverRainZ>`__. + + +`Add span to more items in templates <https://github.com/sunpy/ablog/pull/270>`__ from `Nabil Freij <https://github.com/nabobalis>`__. + +ABlog v0.11.8 released +---------------------- + +Added support for ``sphinx`` >=7.3.0 + +ABlog v0.11.9 released +---------------------- + +`Make '_strip' function return as list not set. <https://github.com/sunpy/ablog/pull/280>`__ from `Joe Ziminski <https://github.com/JoeZiminski>`__. + +ABlog v0.11.10 released +----------------------- + +Fixed wrong branch in the release process. + +ABlog v0.11.11 released +----------------------- + +Mark Ablog parallel safe. + +Dropped support for Python 3.9, Sphinx less than 6.2. +This mirrors the requirements for alabaster 1.0.0. + +ABlog v0.11.12 released +----------------------- + +`Improve ablog-configuration-options.rst. <https://github.com/sunpy/ablog/pull/292>`__ from `Libor Jelínek <https://github.com/liborjelinek>`__. + +`Fix sidebars CSS naming. <https://github.com/sunpy/ablog/pull/298>`__ from `Libor Jelínek <https://github.com/liborjelinek>`__. + +`Ablog is NOT safe for parallel read. <https://github.com/sunpy/ablog/pull/299>`__ from `Libor Jelínek <https://github.com/liborjelinek>`__. + +`Fix theme support for ablog. <https://github.com/sunpy/ablog/pull/295>`__ from `Libor Jelínek <https://github.com/liborjelinek>`__. diff --git a/docs/release/ablog-v0.2-released.rst b/docs/release/ablog-v0.2-released.rst new file mode 100644 index 0000000..9caa3fa --- /dev/null +++ b/docs/release/ablog-v0.2-released.rst @@ -0,0 +1,42 @@ +ABlog v0.2 released +=================== + +.. post:: Aug 31, 2014 + :author: Ahmet + :category: Release + :location: SF + +ABlog v0.2 is released. This version comes with several new features: + + * You can post a document multiple times, see :ref:`posting-sections` + for details. + + * You can make note of updates in a post using :rst:dir:`update` + directive. + + * Blog feeds for authors, locations, categories, tags, and years + can be enabled using :confval:`blog_feed_archives` configuration + variable. + + * Blog Feeds can be made full text using :confval:`blog_feed_fulltext` + configuration variable. + + * Recent posts side bar includes month and day of the posts. + +ABlog v0.2.1 released +--------------------- + +ABlog v0.2.1 is a bug fix release that solves duplicated content +problem in full text atom feeds. + +ABlog v0.2.2 released +--------------------- + +ABlog v0.2.2 is a bug fix release that solves broken links problem +in post lists (:issue:`12`). + +ABlog v0.2.3 released +--------------------- + +ABlog v0.2.3 is a bug fix release that solves broken links (:issue:`13`) +and non-unique post IDs problems atom feeds. diff --git a/docs/release/ablog-v0.3-released.rst b/docs/release/ablog-v0.3-released.rst new file mode 100644 index 0000000..58680ae --- /dev/null +++ b/docs/release/ablog-v0.3-released.rst @@ -0,0 +1,28 @@ +ABlog v0.3 released +=================== + +ABlog v0.3 is released. This version comes with the following core +improvements: + + * You can now specify language of a post with ``:language:`` option, + and an archive page will be created for each language. + See :confval:`blog_languages` and :confval:`blog_default_language` + if you are posting in multiple languages. + + * You can list language archives on your website by adding + ``languages.html`` to :confval:`html_sidebars` configuration option. + + * :rst:dir:`postlist` directive takes options to filter posts. + +ABlog v0.3.1 released +--------------------- + +ABlog v0.3.1 is a minor release to fix two issues in templates: + + * Links to collection (archive) feeds is displayed only on collection page + (e.g. `:ref:`category-manual``), not on a catalog page that lists posts + for multiple collections (e.g. `:ref:`blog-categories``). + + * Links to collection feeds is displayed only when they are generated + (see :confval:`blog_feed_archives`). Previously, links would be generated + to feeds that did not exist. diff --git a/docs/release/ablog-v0.4-released.rst b/docs/release/ablog-v0.4-released.rst new file mode 100644 index 0000000..605680f --- /dev/null +++ b/docs/release/ablog-v0.4-released.rst @@ -0,0 +1,33 @@ +ABlog v0.4 released +=================== + +.. post:: Dec 20, 2014 + :author: Ahmet + :category: Release + :location: SF + +ABlog v0.4 is released. This version comes with the following improvements +and bug fixes: + + * Added :confval:`blog_feed_titles`, :confval:`blog_feed_length`, and + :confval:`blog_archive_titles` configuration options (see :issue:`24`). + + * Set the default for :confval:`blog_feed_archives` to ``False``, which + was set to ``True`` although documented to be otherwise. + + * Fixed issues with :confval:`post_auto_excerpt` and + :confval:`post_auto_image` configuration options. + + * Fixed :issue:`2`, relative size of tags being the minimum size when + all tags have the same number of posts. Now, mean size is + used, and max/min size can be controlled from template. + + * Fixed :issue:`19`. Yearly archives are ordered by recency. + + * Fixed duplicated post title in feeds, :issue:`21`. + + * Fixed :issue:`22`, :rst:dir:`postlist` directive listing more than + specified number of posts. + + * :rst:dir:`postlist` directive accepts arguments to format list items + (:issue:`20`). diff --git a/docs/release/ablog-v0.5-released.rst b/docs/release/ablog-v0.5-released.rst new file mode 100644 index 0000000..fcf1c12 --- /dev/null +++ b/docs/release/ablog-v0.5-released.rst @@ -0,0 +1,15 @@ +ABlog v0.5 released +=================== + +.. post:: Mar 25, 2015 + :author: Ahmet, Mehmet + :category: Release + :location: SF + +ABlog v0.5 is released. This version comes with :ref:`ablog-commands` and +a :ref:`quick-start` guide. + +ABlog v0.5.1 released +--------------------- + +Added ``:excerpts:`` option to :rst:dir:`postlist` directive. diff --git a/docs/release/ablog-v0.6-released.rst b/docs/release/ablog-v0.6-released.rst new file mode 100644 index 0000000..5fed938 --- /dev/null +++ b/docs/release/ablog-v0.6-released.rst @@ -0,0 +1,46 @@ +ABlog v0.6 released +=================== + +.. post:: Apr 8, 2015 + :author: Ahmet + :category: Release + :location: SF + +ABlog v0.6 is released with new :ref:`ablog-commands`. You can use +``ablog deploy`` to :ref:`deploy-to-github-pages`, and also ``ablog clean`` +to do spring cleaning every once in a while. + +ABlog v0.6.1 released +--------------------- + +ABlog v0.6.1 is released with improvements to ``ablog deploy`` command. +It will add ``.nojekyll`` file when needed to deployments to GitHub pages. + +ABlog v0.6.2 released +--------------------- + +ABlog v0.6.2 is released to fix an issue with loading of Disqus comments +(:issue:`33`) and interpreting non-ascii characters (:issue:`34`). + +ABlog v0.6.3 released +--------------------- + +ABlog v0.6.3 comes with Russian localisation and following enhancements: + + * Added ``:list-style:`` option to :rst:dir:`postlist` to enable + controlling bullet list style. + + * ``ablog post`` command de-slugifies filename to make the title + when it's not given. + +ABlog v0.6.4 released +--------------------- + +ABlog v0.6.4 comes with improved ``ablog serve`` command that helps you +:ref:`watch-yourself-blogging`. + +ABlog v0.6.5 released +--------------------- + +ABlog v0.6.5 is a bug fix release to resolve :issue:`38`, an exception raised +when using :rst:dir:`postlist` without specifying number of posts. diff --git a/docs/release/ablog-v0.7-released.rst b/docs/release/ablog-v0.7-released.rst new file mode 100644 index 0000000..a11fbc1 --- /dev/null +++ b/docs/release/ablog-v0.7-released.rst @@ -0,0 +1,92 @@ +ABlog v0.7 released +=================== + +.. post:: May 3, 2015 + :author: Ahmet + :category: Release + :location: Denizli + +ABlog v0.7.0 is released to fix the long standing :issue:`1` related to +pickling of Sphinx build environment on Read The Docs. Improvements +also resolved issues with using LaTeX builder, improved cross-referencing +for non-html builders. + +ABlog v0.7.1 released +--------------------- + +ABlog v0.7.1 is released to fix Python 3 import issues in :command:`ablog serve` +command. + +ABlog v0.7.2 released +--------------------- + +ABlog v0.7.2 is released to prevent potential issues with Disqus thread URLs +by requiring :confval:`disqus_shortname` and :confval:`blog_baseurl` +to be specified together for Disqus integration. + +ABlog v0.7.3 released +--------------------- + +ABlog v0.7.3 makes use of `python-dateutil`__ for parsing post dates, so now you +can be flexible with the format you use in posts. Thanks to `Andy Maloney`__ +for this improvement. + +__ https://pypi.python.org/pypi/python-dateutil +__ https://github.com/amaloney + +ABlog v0.7.5 released +--------------------- + +ABlog v0.7.5 is released to fix Windows specific path resolving issue with +archive pages. Thanks to Peter Mills for reporting this issue. + +ABlog v0.7.6 released +--------------------- + +ABlog v0.7.6 is released to fix path resolving issue that arose when +``:excerpts:`` is used in :rst:dir:`postlist` directive. Once again, thanks +to Peter Mills for reporting this issue. Other minor changes are: + + * ``-P`` argument is added to :ref:`ablog build <build>` command to enable running pdb + on exceptions. + + * ``conf.py`` file created by :ref:`ablog start <start>` updated to include + ``about.html`` sidebar that comes with Alabaster_ theme. + +ABlog v0.7.7 released +--------------------- + +ABlog v0.7.7 is released to fix path resolving :issue:`41` that arose when +cross-references were used in post excerpts, and also post redirect +issue in templates. + +ABlog v0.7.8 released +--------------------- + +ABlog v0.7.8 is released to fix a Python 2 issue that appears when creating +collection pages that contain non-ascii characters in their names (:issue:`45`) +and filename escaping issue when committing changes using +:ref:`ablog deploy <deploy>` command (:pull:`44`). +Thanks to `uralbash`_ for these contributions. + +.. _uralbash: https://github.com/uralbash + +ABlog v0.7.9 released +--------------------- + +ABlog v0.7.9 is released to fix Windows specific file renaming issue in +:ref:`ablog deploy <deploy>` command (:issue:`46`). Thanks to `Velimir`_ +for the fix. + +.. _Velimir: https://github.com/montyvesselinov + +ABlog v0.7.10 released +---------------------- + +ABlog v0.7.10 is released to resolve Sphinx JSON/Pickle builder issues +related to serialization. + +ABlog v0.7.12 released +---------------------- + +ABlog v0.7.12 (and also v0.7.11) maintenance release are available. diff --git a/docs/release/ablog-v0.8-released.rst b/docs/release/ablog-v0.8-released.rst new file mode 100644 index 0000000..cac2afb --- /dev/null +++ b/docs/release/ablog-v0.8-released.rst @@ -0,0 +1,58 @@ +ABlog v0.8 released +=================== + +.. post:: Oct 12, 2015 + :author: Ahmet + :category: Release + :location: SF + +ABlog v0.8.0 is released with additions and changes: + + * Added ``-a`` argument to :ref:`ablog build <build>` command, with which + you can force rewriting all pages when rebuilding your project. Default is + writing only pages that have changed. + + * Added ``-f`` argument to :ref:`ablog deploy <deploy>` command, with which + you can amend to latest commit to keep GitHub pages repository small. + Thanks to `uralbash`_ for this contribution. + + * Added ``-p`` argument to :ref:`ablog deploy <deploy>` command, with which + you can specify the path to your GitHub pages repository, i.e. + ``username.github.io``. + + * Changed :confval:`fontawesome_link_cdn` to be a string argument to enable + linking to desired version of `Font Awesome`_. Thanks to `Albert Mietus`_ + for this contribution. + + * Post lists font style is now controlled through CSS. Thanks to + `Albert Mietus`_ for this contribution as well. + + * Fixed internal link resolution issue that affected atom feeds of + collections, i.e. feeds of posts under a category, tag, or author. + +.. _Font Awesome: https://fontawesome.com/ +.. _Albert Mietus: https://github.com/AlbertMietus +.. _uralbash: https://github.com/uralbash + +ABlog v0.8.1 released +--------------------- + +ABlog v0.8.1 is released to fix atom feed linking in HTML header (:issue:`54`). + +ABlog v0.8.2 released +--------------------- + +ABlog v0.8.2 is released to fix date parsing (:issue:`58`) and Python 2.6 +installation (:issue:`59`) issues. + +ABlog v0.8.3 released +--------------------- + +ABlog v0.8.3 is released to bring you recent enhancements: + + * `ninmesara`_ added ``:nocomments:`` argument to :rst:dir:`post` directive + to disable comments per post. + * `José Carlos García`_ added Spanish translations. + +.. _ninmesara: https://github.com/ninmesara +.. _José Carlos García: https://github.com/quobit diff --git a/docs/release/ablog-v0.9-released.rst b/docs/release/ablog-v0.9-released.rst new file mode 100644 index 0000000..bb7a77f --- /dev/null +++ b/docs/release/ablog-v0.9-released.rst @@ -0,0 +1,61 @@ +ABlog v0.9 released +=================== + +.. post:: Feb 17, 2018 + :author: Nabil Freij + :category: Release + :location: World + +ABlog v0.9.0 is released with the main focus being to support the latest version of Sphinx. +This also moves the main development from `Abakan`_ to `SunPy`_. + +This has merged in all current (at time of writing, 6) open PRs to the original repository. + +These are: + +`fix(commands): Update command arguments so patterns works correctly <https://github.com/abakan-zz/ablog/pull/96>`__ from `rayalan <https://github.com/rayalan>`__. + +`Fix couple of bugs with latest stable Sphinx <https://github.com/abakan-zz/ablog/pull/93>`__ from `tadeboro <https://github.com/tadeboro>`__. + +`don't use fancy quotes in the conf.py template <https://github.com/abakan-zz/ablog/pull/87>`__ from `tiwo <https://github.com/tiwo>`__. + +`Pass through additional Sphinx options and fix a typo <https://github.com/abakan-zz/ablog/pull/84>`__ from `ahrbel <https://github.com/ahrbe1>`__. + +`fix #78 (ImportError: cannot import name make_admonition in Sphinx 1.6) <https://github.com/abakan-zz/ablog/pull/79>`_ from `lsaffre <https://github.com/lsaffre>`__. + +`Raise exception when title is missing <https://github.com/abakan-zz/ablog/pull/76>`__ from `rgrinberg <https://github.com/rgrinberg>`__. + +.. _Abakan: https://github.com/abakan/ablog +.. _SunPy: https://github.com/sunpy/ablog + +ABlog v0.9.1 released +--------------------- + +Minor update to remove Ablog{}.format(python_number) exes + +ABlog v0.9.2 released +--------------------- + +Fixed Windows String issue. + +ABlog v0.9.3 released +--------------------- + +Added example on how to use writing blog posts in Jupyter notebooks. + +`show </span> when if fa <https://github.com/sunpy/ablog/pull/22>`__, `Add create file encoding <https://github.com/sunpy/ablog/pull/23>`__ and `fix serve command path <https://github.com/sunpy/ablog/pull/31>`__ from `anzawatta <https://github.com/anzawatta>`__. + +Sorry I was late to release these! + +ABlog v0.9.4 released +--------------------- + +Fixes for gettext break and some pathing issues. + +ABlog v0.9.5 released +--------------------- + +v0.9.5 is the that supports Python 2 and Sphinx <2. +v0.10.0 on main now, will not. + +`Define an auto-orphan option <https://github.com/sunpy/ablog/pull/39>`__, `Repair update directive <https://github.com/sunpy/ablog/pull/37>`__ and `Fix sidebar and blog_baseurl misconfig during quick start <https://github.com/sunpy/ablog/pull/36>`__ from `rayalan <https://github.com/rayalan>`__. |
