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

https://fontawesome.com/kits/1ac8069c6b/use?welcome=yes

Site Map

pip install sphinx-sitemap

config.py set:

extensions = ['sphinx_sitemap']
html_baseurl = 'https://my-site.com/docs/'

Disqus

https://disqus.com/admin/

Content Style

Search Engine

Comments

comments powered by Disqus