Moved blog to alabaster with Sphinx¶
Mostly notes to self on how to deploy and architecture / setup. Inspired by https://github.com/vincentbernat/vincent.bernat.ch
Some other good examples: - https://github.com/pyinvoke/invoke/blob/master/sites/www/prior-art.rst - https://www.pyinvoke.org/prior-art.html
Serve¶
Cloudfront –> S3 Bucket
Tips
Do not set the default resource on cloudfront (index.html). leave it blank
Configure the S3 bucket for “Static website hosting” with “Hosting Type = Bucket hosting” and configure bucket with the default resources (index.html)
Configure cloudfront to point origin as the S3 hosting URL NOT the S3 bucket from the dropdown example: http://cetinichblog.s3-website-us-east-1.amazonaws.com
When uploading objects set acl for public-read
Bucket Policy:
{
"Version": "2008-10-17",
"Id": "make bucket public",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::cetinichblog/*"
}
]
}
Preview¶
To have automatic regeneration when files change pip install watchdog
then
use ablog -r
To build the site and launch the browser:
ablog build; ablog serve -r
Without this the css will not update:
rm -rf ~/blog/_website/ ; ablog build; ablog serve -r
Live Dev¶
#TODO https://pypi.org/project/sphinx-autobuild/
To do local dev for other html use ngrok
, (it is a node JS app). This will
allow you to serve static content locally or accessible via the internet (if you
don’t sign up to the service it only works on the internet for 2 hours). It also
injects some JS helpers to auto refresh files as you change them.
npx ngrok http 5500
The content is served locally here
Or if you do not have a web server ask ngrok to do that also by specifying a file:
npx ngrok http -region=ap -auth="user:password" file:////home/brent/blog/
Or without fist running ablog service, more generically you can serve any directory like this:
python -m http.server 8881 & npx ngrok http 8881
If you have utf-8 stuff then its better to do this:
python3 -c "from http.server import test, SimpleHTTPRequestHandler as RH; RH.extensions_map={k:v+';charset=UTF-8' for k,v in RH.extensions_map.items()}; test(RH)"
Deploy¶
aws s3 sync --delete --acl public-read ./_website/ s3://cetinichblog/production/
aws cloudfront create-invalidation --distribution-id E2A3F01FBNYPBD --paths "/*"
Customization¶
Alabaster Solarised Dark Theme¶
Follow the instructions, the only deviation I had to make was instead of using
the setup(app)
use this
html_css_files = [
'css/custom.css',
]
Spaces in inline literals are white¶
Add this to custom.css
and match background-color
with the
background-color
of span.pre
(or whatever you want):
tt,
code {
color: #839496;
background-color: #073642;
}
Metadata on posts¶
The metadata on the posts are configured using Ablog
Font Awesome CDN¶
Site Map¶
pip install sphinx-sitemap
config.py set:
extensions = ['sphinx_sitemap']
html_baseurl = 'https://my-site.com/docs/'
Disqus¶
Content Style¶
VSCode rewrap plugin (alt+q) very helpful for sticking to column size.