From 883cc96871774beadd5c01b8aaa8c10a3b4be864 Mon Sep 17 00:00:00 2001 From: Nabil Freij Date: Sat, 10 Oct 2020 10:21:52 +0100 Subject: [PATCH] Various issues --- .pre-commit-config.yaml | 2 +- .travis.yml | 28 ---- README.rst | 7 - ablog/post.py | 9 +- ablog/start.py | 4 +- appveyor.yml | 41 ------ azure-pipelines.yml | 84 +++++++----- docs/conf.py | 34 ++--- docs/index.rst | 36 ++--- docs/manual/ablog-commands.rst | 47 ++----- docs/manual/ablog-configuration-options.rst | 134 +++++++------------ docs/manual/ablog-i18n.rst | 31 ++--- docs/manual/ablog-quick-start.rst | 85 +++++------- docs/manual/auto-github-pages-deploys.rst | 58 +++----- docs/manual/cross-referencing-blog-pages.rst | 17 +-- docs/manual/deploy-to-github-pages.rst | 9 +- docs/manual/forever-draft.rst | 21 +-- docs/manual/markdown.md | 54 ++++++++ docs/manual/post-excerpts-and-images.rst | 26 ++-- docs/manual/posting-and-listing.rst | 92 +++++-------- docs/manual/watch-yourself-blogging.rst | 14 +- docs/release/ablog-v0.1-released.rst | 2 +- docs/release/ablog-v0.10-released.rst | 134 ++++++++++++++++++- docs/release/ablog-v0.2-released.rst | 4 - docs/release/ablog-v0.3-released.rst | 2 - docs/release/ablog-v0.4-released.rst | 1 - docs/release/ablog-v0.5-released.rst | 1 - docs/release/ablog-v0.6-released.rst | 6 - docs/release/ablog-v0.7-released.rst | 11 -- docs/release/ablog-v0.8-released.rst | 9 -- docs/release/ablog-v0.9-released.rst | 51 +++++-- setup.cfg | 4 +- tox.ini | 74 ++++++++++ 33 files changed, 573 insertions(+), 559 deletions(-) delete mode 100644 .travis.yml delete mode 100644 appveyor.yml create mode 100644 docs/manual/markdown.md create mode 100644 tox.ini diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0eb196de..86037482 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -4,7 +4,7 @@ repos: hooks: - id: black - repo: https://github.com/timothycrosley/isort - rev: 5.5.1 + rev: 5.6.1 hooks: - id: isort - repo: https://github.com/pre-commit/pre-commit-hooks diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 6161d9a9..00000000 --- a/.travis.yml +++ /dev/null @@ -1,28 +0,0 @@ -language: c - -os: - - linux - -sudo: false - -env: - matrix: - - PYTHON_VERSION=3.6 SPHINX_VERSION=2.4 - - PYTHON_VERSION=3.6 SPHINX_VERSION=3.2 - - PYTHON_VERSION=3.7 SPHINX_VERSION=2.4 - - PYTHON_VERSION=3.7 SPHINX_VERSION=3.2 - - PYTHON_VERSION=3.8 SPHINX_VERSION=2.4 - - PYTHON_VERSION=3.8 SPHINX_VERSION=3.2 - - global: - - LOCALE=default - - CONDA_CHANNELS="conda-forge" - - CONDA_DEPENDENCIES="pandoc" - -install: - - git clone git://github.com/astropy/ci-helpers.git - - source ci-helpers/travis/setup_conda.sh - - pip install -e .[all,docs] - -script: - - make tests diff --git a/README.rst b/README.rst index 87e00161..a661493a 100644 --- a/README.rst +++ b/README.rst @@ -1,13 +1,6 @@ ABlog for Sphinx ================ -.. image:: https://travis-ci.org/sunpy/ablog.svg?branch=master - :target: https://travis-ci.org/sunpy/ablog -.. image:: https://circleci.com/gh/sunpy/ablog.svg?style=svg - :target: https://circleci.com/gh/sunpy/ablog -.. image:: https://ci.appveyor.com/api/projects/status/cmmiadqoy5lx7l78?svg=true - :target: https://ci.appveyor.com/project/sunpy/ablog - Note ---- diff --git a/ablog/post.py b/ablog/post.py index 8831a5bf..8b229fe7 100644 --- a/ablog/post.py +++ b/ablog/post.py @@ -151,9 +151,12 @@ def run(self): class CheckFrontMatter(SphinxTransform): - """Check the doctree for frontmatter meant for a blog post. + """ + Check the doctree for frontmatter meant for a blog post. - This is mutually-exclusive with the PostDirective. Only one much be used.""" + This is mutually-exclusive with the PostDirective. Only one much be + used. + """ # Priority before 880 so that it runs before the `doctree-read` event default_priority = 800 @@ -538,7 +541,7 @@ def process_postlist(app, doctree, docname): def missing_reference(app, env, node, contnode): target = node["reftarget"] - logging.warning(f"error, missing reference: {target}, {contnode}") + logging.debug(f"missing reference: {target}, {contnode}") return _missing_reference(app, target, node.get("refdoc"), contnode, node.get("refexplicit")) diff --git a/ablog/start.py b/ablog/start.py index dce79c35..85adf398 100644 --- a/ablog/start.py +++ b/ablog/start.py @@ -418,10 +418,10 @@ def w(t, ls=80): World, hello again! This very first paragraph of the post will be used as excerpt in archives and feeds. Find out how to control how much is shown in `Post Excerpts and Images -`_. Remember +`__. Remember that you can refer to posts by file name, e.g. ``:ref:`first-post``` results in :ref:`first-post`. Find out more at `Cross-Referencing Blog Pages -`_. +`__. """ diff --git a/appveyor.yml b/appveyor.yml deleted file mode 100644 index 6da5ccbe..00000000 --- a/appveyor.yml +++ /dev/null @@ -1,41 +0,0 @@ -# AppVeyor.com is a Continuous Integration service to build and run tests under Windows - -environment: - matrix: - - PY_MAJOR_VER: 3 - PYTHON_ARCH: "x86_64" - -build: false - -matrix: - fast_finish: true - -platform: - - x64 - -os: Visual Studio 2017 - -install: - - ps: >- - if (-Not (Test-Path "C:\Program Files\Pandoc\")) { - cinst pandoc --no-progress - cinst graphviz --no-progress - } - - ps: $env:Path += ";C:\Program Files\Pandoc\" - - ps: Start-FileDownload "https://repo.continuum.io/miniconda/Miniconda$env:PY_MAJOR_VER-latest-Windows-$env:PYTHON_ARCH.exe" C:\Miniconda.exe; echo "Finished downloading miniconda" - - cmd: C:\Miniconda.exe /S /D=C:\Py - - cmd: SET PATH=C:\Py;C:\Py\Scripts;C:\Py\Library\bin;%PATH% - - cmd: conda config --set always_yes yes - - cmd: conda update conda --quiet - - cmd: conda config --add channels conda-forge - - cmd: conda config --set channel_priority strict - - cmd: conda install pandoc --quiet - - cmd: pip install -e .[all,docs] - -test_script: - - python setup.py build_sphinx - - ps: cd docs - - ablog build -T - - ablog build -b latex -T -d .doctrees -w _latex - - ablog build -T -b json - - ablog build -T -b pickle diff --git a/azure-pipelines.yml b/azure-pipelines.yml index 7d405f9e..e4e689c1 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -1,36 +1,56 @@ -# Python package -# Create and test a Python package on multiple Python versions. -# Add steps that analyze code, save the dist with the build record, publish to a PyPI-compatible index, and more: -# https://docs.microsoft.com/azure/devops/pipelines/languages/python +name: $(BuildDefinitionName)_$(Date:yyyyMMdd)$(Rev:.rr) -trigger: -- master - -pool: - vmImage: 'ubuntu-latest' -strategy: - matrix: - Python27: - python.version: '2.7' - Python35: - python.version: '3.5' - Python36: - python.version: '3.6' - Python37: - python.version: '3.7' +schedules: + - cron: "0 0 * * *" + displayName: Daily midnight build + branches: + include: + - master + always: true -steps: -- task: UsePythonVersion@0 - inputs: - versionSpec: '$(python.version)' - displayName: 'Use Python $(python.version)' +resources: + repositories: + - repository: OpenAstronomy + type: github + endpoint: sunpy + name: OpenAstronomy/azure-pipelines-templates + ref: master -- script: | - python -m pip install --upgrade pip - pip install -r requirements.txt - displayName: 'Install dependencies' +trigger: + branches: + include: + - '*' + exclude: + - '*backport*' + tags: + include: + - 'v*' + exclude: + - '*dev*' + - '*pre*' + - '*post*' -- script: | - pip install pytest pytest-azurepipelines - pytest - displayName: 'pytest' +jobs: +- template: run-tox-env.yml@OpenAstronomy + parameters: + submodules: false + coverage: codecov + libraries: + brew: + - pandoc + choco: + - pandoc + apt: + - pandoc + envs: + - macos: py36-sphinx2 + - windows: py36-sphinx3 + - linux: codestyle + name: python_codestyle + pytest: false + - linux: py37-sphinx2 + - linux: py37-sphinx3 + - linux: py38-sphinx2 + - linux: py38-sphinx3 + - linux: py38-devdeps + - linux: py38-conda diff --git a/docs/conf.py b/docs/conf.py index 1c59e036..bd423cfe 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,7 +6,6 @@ ablog_builder = "dirhtml" ablog_website = "_website" - extensions = [ "sphinx.ext.autodoc", "sphinx.ext.doctest", @@ -17,15 +16,13 @@ "sphinx_automodapi.automodapi", "alabaster", "nbsphinx", + "myst_parser", "ablog", ] -# language = 'de' -# language = 'tr' # PROJECT - versionmod = get_distribution("ablog") - +myst_update_mathjax = False # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. @@ -35,16 +32,16 @@ release = versionmod.version.split("+")[0] # Is this version a development release is_development = ".dev" in release - project = "ABlog" -copyright = "2014-2019, ABlog Team" +copyright = "2014-2021, ABlog Team" master_doc = "index" -source_suffix = ".rst" +source_suffix = { + ".rst": "restructuredtext", + ".md": "markdown", +} exclude_patterns = ["_build"] - # HTML OUTPUT - html_title = "ABlog" html_static_path = ["_static"] html_use_index = True @@ -53,7 +50,6 @@ html_favicon = "_static/ablog.ico" # ABLOG - blog_title = "ABlog" blog_baseurl = "https://ablog.readthedocs.org" blog_locations = { @@ -74,14 +70,8 @@ disqus_shortname = "ablogforsphinx" disqus_pages = True fontawesome_css_file = "css/font-awesome.css" -blog_post_pattern = "release/ablog-v0.1-released*" - -# blog_feed_titles = False -# blog_archive_titles = False -# post_auto_excerpt = 1 # THEME - html_style = "alabaster.css" html_theme = "alabaster" html_sidebars = { @@ -97,7 +87,7 @@ } html_theme_path = [alabaster.get_path()] html_theme_options = { - "travis_button": True, + "travis_button": False, "github_user": "sunpy", "github_repo": "ablog", "description": "ABlog for blogging with Sphinx", @@ -105,20 +95,16 @@ } # SPHINX - 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", ""), "issue": ("https://github.com/sunpy/ablog/issues/%s", "issue "), "pull": ("https://github.com/sunpy/ablog/pull/%s", "pull request "), } - exclude_patterns = ["docs/manual/.ipynb_checkpoints/*"] - rst_epilog = """ .. _Sphinx: http://sphinx-doc.org/ .. _Python: https://python.org @@ -130,10 +116,8 @@ """ -event_sig_re = re.compile(r"([a-zA-Z-]+)\s*\((.*)\)") - - 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) diff --git a/docs/index.rst b/docs/index.rst index 887c07a3..7d077f03 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,8 +1,7 @@ ABlog for Sphinx ================ -ABlog is a Sphinx extension that converts any documentation or personal -website project into a full-fledged blog with: +ABlog is a Sphinx extension that converts any documentation or personal website project into a full-fledged blog with: * `Atom feeds`_ * `Archive pages`_ @@ -10,6 +9,7 @@ website project into a full-fledged blog with: * `Disqus integration`_ * `Font-Awesome integration`_ * `Easy GitHub Pages deploys`_ + * `Markdown support`_ .. _Atom feeds: https://ablog.readthedocs.io/blog/atom.xml .. _Archive pages: https://ablog.readthedocs.io/blog/archive.html @@ -17,6 +17,7 @@ website project into a full-fledged blog with: .. _Disqus integration: https://ablog.readthedocs.io/manual/ablog-configuration-options.html#disqus-integration .. _Font-Awesome integration: https://ablog.readthedocs.io/manual/ablog-configuration-options.html#fa .. _Easy GitHub Pages deploys: https://ablog.readthedocs.io/manual/auto-github-pages-deploys.html +.. _Markdown support: https://ablog.readthedocs.io/manual/markdown.html .. _installation: @@ -39,7 +40,6 @@ Getting Started --------------- If you are starting a new project, see `ABlog Quick Start`_ guide. - If you already have a project, enable blogging by making following changes in ``conf.py``: .. code-block:: python @@ -51,16 +51,13 @@ If you already have a project, enable blogging by making following changes in `` 'sphinx.ext.intersphinx', ] - .. _ABlog Quick Start: https://ablog.readthedocs.io/manual/ablog-quick-start.html 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: +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: http://www.sphinx-doc.org/en/master/ @@ -73,8 +70,20 @@ content (in ``.rst`` files), you can post *any page* using the :location: SF :language: en -ABlog will index all files posted as above and list them in archives and feeds -specified in ``:tag:``, ``:category:``, etc. options. +An alterative 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: @@ -86,8 +95,7 @@ You can also include a list of posts using :rst:dir:`postlist` directive: :format: {title} :sort: -For ABlog documentation, this converts to the following where you -can find more about configuring and using ABlog: +For ABlog documentation, this converts to the following where you can find more about configuring and using ABlog: .. postlist:: :category: Manual @@ -97,13 +105,9 @@ can find more about configuring and using ABlog: .. only:: html - .. image:: https://secure.travis-ci.org/sunpy/ablog.png?branch=devel - :target: https://travis-ci.org/#!/sunpy/ablog - .. image:: https://readthedocs.org/projects/ablog/badge/?version=latest :target: https://ablog.readthedocs.org/ - .. toctree:: :hidden: :glob: diff --git a/docs/manual/ablog-commands.rst b/docs/manual/ablog-commands.rst index 519facf5..65d84fe5 100644 --- a/docs/manual/ablog-commands.rst +++ b/docs/manual/ablog-commands.rst @@ -10,10 +10,7 @@ ABlog Commands :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`` 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} ... @@ -35,22 +32,17 @@ and viewing blog pages, as well as starting a new blog. See 'ablog -h' for more information on a specific command. - .. contents:: Here are all the things you can do: - :local: - :backlinks: top + :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`` 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] @@ -61,16 +53,12 @@ Start a New Project 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. - -:: +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] @@ -93,14 +81,10 @@ Running ``ablog build`` in your project folder builds your website HTML pages. -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. - -:: +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] @@ -117,15 +101,12 @@ server and open up browser tab to view your website. -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. - -:: +Running ``ablog deploy`` will push your website to GitHub:: $ ablog deploy -h usage: ablog deploy [-h] [-w WEBSITE] [-p REPODIR] [-g GITHUB_PAGES] @@ -149,13 +130,10 @@ Running ``ablog deploy`` will push your website to GitHub. --github-token GITHUB_TOKEN environment variable name storing GitHub access token - Create a Post ------------- -Finally, ``ablog post`` will make a new post template file. - -:: +Finally, ``ablog post`` will make a new post template file:: $ ablog post -h usage: ablog post [-h] [-t TITLE] filename @@ -167,14 +145,10 @@ Finally, ``ablog post`` will make a new post template file. -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. - -:: +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] @@ -190,7 +164,6 @@ do a deep clean with ``-D`` option. 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 index 7998fba9..83d042b3 100644 --- a/docs/manual/ablog-configuration-options.rst +++ b/docs/manual/ablog-configuration-options.rst @@ -10,8 +10,7 @@ ABlog Configuration Options :location: Pittsburgh -This post describes ABlog configuration options that go in -:ref:`Sphinx build configuration file `. +This post describes ABlog configuration options that go in :ref:`Sphinx build configuration file `. General options --------------- @@ -21,7 +20,6 @@ General options A path relative to the configuration directory for blog archive pages. Default is ``'blog'``. - .. confval:: blog_title The “title” for the blog, used in acthive pages. Default is ``'Blog'``. @@ -30,21 +28,19 @@ General options Base URL for the website, required for generating feeds. - .. confval:: blog_archive_titles - Choose to archive only post titles in collection pages, default is - ``False``. - + Choose to archive only post titles in collection pages, default is ``False``. 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:: + 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'), @@ -54,24 +50,21 @@ Authors, languages, & locations .. 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:: + 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_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. + 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_author Name of the default author defined in :confval:`blog_authors`. @@ -87,49 +80,41 @@ Authors, languages, & locations 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. + 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'``) for published posts that - goes as input to :meth:`datetime.date.strftime`. + Date display format (default is ``'%b %d, %Y'``) 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``. + 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``. + 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. + 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``. - - + 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``. Blog feeds ---------- @@ -138,8 +123,7 @@ Turn feeds on by setting :confval:`blog_baseurl` configuration variable. .. confval:: blog_feed_archives - Choose to create feeds per author, location, tag, category, and year, - default is ``False``. + Choose to create feeds per author, location, tag, category, and year, default is ``False``. .. confval:: blog_feed_fulltext @@ -155,69 +139,56 @@ Turn feeds on by setting :confval:`blog_baseurl` configuration variable. .. confval:: blog_feed_length - Specify number of recent posts to include in feeds, default is ``None`` - for all posts. + 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. + 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. + Added :confval:`blog_feed_titles`, :confval:`blog_feed_length`, and :confval:`blog_archive_titles` options. .. _fa: Font awesome ------------ -ABlog templates will use of `Font Awesome`_ icons if one of the following -is set: +ABlog templates will use of `Font Awesome`_ icons if one of the following is set: .. _Font Awesome: https://fontawesome.io/ - .. confval:: fontawesome_link_cdn - URL to `Font Awesome`_ :file:`.css` hosted at `Bootstrap CDN`_ or anywhere - else. Default: ``None`` + 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_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`` + 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: +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. + 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. +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 @@ -229,17 +200,15 @@ serve new posts locally for the first time. .. confval:: disqus_drafts - Choose to disqus posts that are drafts (without a published date), - default is ``False``. + Choose to disqus posts that are drafts (without a published date), default is ``False``. .. _sidebars: Blog sidebars ------------- -Finally, there are seven sidebars you can include in your HTML output -using Sphinx_ :confval:`html_sidebars` configuration option. Sidebars that -you see on the left are listed below in the same order: +Finally, there are seven sidebars you can include in your HTML output using Sphinx_ :confval:`html_sidebars` configuration option. +Sidebars that you see on the left are listed below in the same order: .. code-block:: python @@ -252,10 +221,9 @@ you see on the left are listed below in the same order: :file:`postcard.html` provides information regarding the current post. -:file:`recentposts.html` lists most recent five posts. Others provide a -link to a archive pages generated for each tag, category, and year. -In addition, there are ``authors.html``, ``languages.html``, and -``locations.html`` sidebars that link to author and location archive pages. +:file:`recentposts.html` lists most recent five posts. +Others provide a link to a archive pages generated for each tag, category, and year. +In addition, there are ``authors.html``, ``languages.html``, and ``locations.html`` sidebars that link to author and location archive pages. Command Options --------------- @@ -274,12 +242,10 @@ Command Options .. 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. + 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. + 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 index cdab1458..11d46463 100644 --- a/docs/manual/ablog-i18n.rst +++ b/docs/manual/ablog-i18n.rst @@ -6,24 +6,21 @@ ABlog Internationalization :category: Manual :author: Luc, Ahmet -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 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: +ABlog needs your help for translation of these labels. +Translation process involves the following steps: 1. Update translatable messages: - Execute extract_messages_ each time a translatable message text is changed - or added:: + Execute extract_messages_ each time a translatable message text is changed or added:: - $ python setup.py extract_messages -o ablog/locale/sphinx.pot - ... + $ python setup.py extract_messages -o ablog/locale/sphinx.pot + ... - This will create or update :file:`ablog/locale/sphinx.pot` file, the - central messages catalog used by the different translations. + This will create or update :file:`ablog/locale/sphinx.pot` file, the central messages catalog used by the different translations. 2. @@ -33,29 +30,23 @@ involves the following steps: $ python setup.py init_catalog -l de -i ablog/locale/sphinx.pot -o ablog/locale/de/LC_MESSAGES/sphinx.po - This will create a file :file:`ablog/locale/de/LC_MESSAGES/sphinx.po` - in which translations needs to be placed. + This will create a file :file:`ablog/locale/de/LC_MESSAGES/sphinx.po` in which translations needs to be placed. b. Update translation catalog: - Execute update_catalog_ for each *existing* language, e.g.:: $ python setup.py update_catalog -l de -i ablog/locale/sphinx.pot -o ablog/locale/de/LC_MESSAGES/sphinx.po - This will update file :file:`ablog/locale/de/LC_MESSAGES/sphinx.po` - where translations of new text needs to be placed. + This will update file :file:`ablog/locale/de/LC_MESSAGES/sphinx.po` where translations of new text needs to be placed. 3. Compile catalogs: - Execute compile_catalog_ for each existing language, e.g.:: + Execute compile_catalog_ for each existing language, e.g:: $ python setup.py compile_catalog --directory ablog/locale/ --domain sphinx --locale de - .. _extract_messages: http://babel.edgewall.org/wiki/Documentation/setup.html#extract-messages - .. _init_catalog: http://babel.edgewall.org/wiki/Documentation/setup.html#init-catalog - .. _update_catalog: http://babel.edgewall.org/wiki/Documentation/setup.html#update-catalog .. _compile_catalog: http://babel.edgewall.org/wiki/Documentation/setup.html#id4 diff --git a/docs/manual/ablog-quick-start.rst b/docs/manual/ablog-quick-start.rst index ab046455..c4dcb490 100644 --- a/docs/manual/ablog-quick-start.rst +++ b/docs/manual/ablog-quick-start.rst @@ -10,59 +10,48 @@ ABlog Quick Start :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. +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: +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:`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:`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. +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`_ useful. +If you are new to Sphinx_ and reStructuredText markup language, you might find `reStructuredText Primer`_ useful. .. _reStructuredText Primer: http://sphinx-doc.org/rest.html - 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`. +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 @@ -71,11 +60,10 @@ 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 front-matter rather than a directive using ABlog. +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 @@ -86,56 +74,53 @@ Simply use something based on the following template as the front-matter:: :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 Comments -------- -You can enable comments in your website by creating a Disqus_ account and -obtaining a unique identifier, i.e. :confval:`disqus_shortname`. +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. +ABlog uses Alabaster_ theme by default. You can use theme options to set your `Google Analytics`_ identifier to enable tracking. .. _Google Analytics: 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 `_ - and `project information `_ +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. - * :ref:`html-options` - configure appearance of your website + * `General configuration `__ and `project information `__ - * Alabaster_ theme options - link to your GitHub account and project, set up - tracking, etc. + * :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: +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:`_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. + * :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/auto-github-pages-deploys.rst b/docs/manual/auto-github-pages-deploys.rst index b5919e4e..4bcdba5b 100644 --- a/docs/manual/auto-github-pages-deploys.rst +++ b/docs/manual/auto-github-pages-deploys.rst @@ -9,59 +9,49 @@ Automate GitHub Pages Deploys :language: en -If being away from your personal computer is holding you back from blogging, keep -reading. This post will show you how to automate builds and deploys using -Travis CI. Once you set this up, all you need to do post an article will be -pushing to GitHub or creating a new file on `GitHub.com `_ -from any computer! +If being away from your personal computer is holding you back from blogging, keep reading. +This post will show you how to automate builds and deploys using Travis CI. +Once you set this up, all you need to do post an article will be pushing to GitHub or creating a new file on `GitHub.com `__ from any computer! For this to work, you need to be hosting your website on GitHub pages. If you are not already doing so, see :ref:`deploy-to-github-pages`. +Sign up for Travis CI +--------------------- -Signup for Travis CI --------------------- - -Travis CI is a continuous integration service used to build and test projects -hosted at GitHub. You can easily sync your GitHub projects with Travis CI -signing up for Travis CI using your GitHub account: +Travis CI is a continuous integration service used to build and test projects hosted at GitHub. +You can easily sync your GitHub projects with Travis CI signing up for Travis CI using your GitHub account: .. figure:: images/TravisCI_login.png :scale: 80 % :align: center - -Once you login, go to :guilabel:`Accounts` page and flick the switch on for your -source repository for GitHub pages. In the below example, **website** is the -source repository and *sunpy.github.io* contains HTML output from builds: +Once you login, go to :guilabel:`Accounts` page and flick the switch on for your source repository for GitHub pages. +In the below example, **website** is the source repository and *sunpy.github.io* contains HTML output from builds: .. figure:: images/TravisCI_accounts.png :scale: 80 % :align: center - Deploy key setup ---------------- -To have builds pushed from Travis CI to GitHub, you will need a *personal access -token*. Go to GitHub :menuselection:`Settings --> Personal access tokens` page to -generate a new token. You need only *public repo* access checked for this purpose: +To have builds pushed from Travis CI to GitHub, you will need a *personal access token*. +Go to GitHub :menuselection:`Settings --> Personal access tokens` page to generate a new token. +You need only *public repo* access checked for this purpose: .. figure:: images/GitHub_token.png :scale: 80 % :align: center -Then, you need to set this access token as an environment variable, e.g. -``DEPLOY_KEY``, under :menuselection:`Settings --> Environment Variables`. -Keep the :guilabel:Display value in build logs` switch off. +Then, you need to set this access token as an environment variable, e.g. ``DEPLOY_KEY``, under :menuselection:`Settings --> Environment Variables`. +Keep the :guilabel:`Display value in build logs switch off`. .. figure:: images/TravisCI_settings.png :scale: 80 % :align: center - -Also, do not forget to flick :guilabel:`Build pushes` on under -:menuselection:`Settings --> General Settings`: +Also, do not forget to flick :guilabel:`Build pushes` on under :menuselection:`Settings --> General Settings`: .. figure:: images/TravisCI_global.png :scale: 65 % @@ -70,9 +60,7 @@ Also, do not forget to flick :guilabel:`Build pushes` on under Configuration file ------------------ -Finally, you need a :file:`.travis.yml` in your project that looks like the -following: - +Finally, you need a :file:`.travis.yml` in your project that looks like the following: .. code-block:: yaml @@ -96,16 +84,12 @@ following: - git config --global push.default simple - ablog deploy --push-quietly --github-token=DEPLOY_KEY -m="`git log -1 --pretty=%B`" - The main part of the process, that is building of the website, is under ``script`` block. -If you repository has dependencies to other Python packages, you can install them -in ``before_install`` block. +If you repository has dependencies to other Python packages, you can install them in ``before_install`` block. -Upon a successful built, your website is deployed. Note that there is no -mention of your GitHub Pages repository, i.e. ``username.github.io``. +Upon a successful built, your website is deployed. +Note that there is no mention of your GitHub Pages repository, i.e. ``username.github.io``. That is specified in :file:`conf.py` file with :confval:`github_pages`. -See :ref:`deploy-to-github-pages` and :ref:`commands` to find out more about -deploy options. +See :ref:`deploy-to-github-pages` and :ref:`commands` to find out more about deploy options. -Finally, you can find out more about :file:`.travis.yml` file and customizing your built on -Travis CI `user documentation `_. +Finally, you can find out more about :file:`.travis.yml` file and customizing your built on Travis CI `user documentation `__. diff --git a/docs/manual/cross-referencing-blog-pages.rst b/docs/manual/cross-referencing-blog-pages.rst index 99d715d6..b39521e0 100644 --- a/docs/manual/cross-referencing-blog-pages.rst +++ b/docs/manual/cross-referencing-blog-pages.rst @@ -7,25 +7,20 @@ Cross-referencing Blog Pages :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. +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. +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. +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 pages, on the other hand, can be cross-referenced by combining archive type and archive name as follows: ============== ========================== =============================== Archive Example reStructured Text diff --git a/docs/manual/deploy-to-github-pages.rst b/docs/manual/deploy-to-github-pages.rst index 5638a83e..9c7a546f 100644 --- a/docs/manual/deploy-to-github-pages.rst +++ b/docs/manual/deploy-to-github-pages.rst @@ -9,16 +9,13 @@ Deploy to GitHub Pages :category: Manual :location: SF -If you are looking for a place to publish your blog, `GitHub Pages`_ might -be the place for you. +If you are looking for a place to publish your blog, `GitHub Pages`_ might be the place for you. .. _GitHub Pages: https://pages.github.com/ -Assuming that you have a GitHub account, here are what you need to do -to get published: +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. +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 ;) diff --git a/docs/manual/forever-draft.rst b/docs/manual/forever-draft.rst index 43144708..9d0753f9 100644 --- a/docs/manual/forever-draft.rst +++ b/docs/manual/forever-draft.rst @@ -6,14 +6,12 @@ Draft Example :category: Manual -As the title suggests, this is a draft example and shall remain so until -the end of time or internet. +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: +Just indicate that the page is a post using :rst:dir:`post` directive, but do not provide give a published date: .. code-block:: rst @@ -21,22 +19,15 @@ but do not provide give a published date: :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. +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-drafs```. - +See :ref:`blog-drafts` archive page, which can be referred to as ``:ref:blog-drafs```. 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. +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/markdown.md b/docs/manual/markdown.md new file mode 100644 index 00000000..1a6df656 --- /dev/null +++ b/docs/manual/markdown.md @@ -0,0 +1,54 @@ +--- +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/post-excerpts-and-images.rst b/docs/manual/post-excerpts-and-images.rst index 85f523ac..68cd1066 100644 --- a/docs/manual/post-excerpts-and-images.rst +++ b/docs/manual/post-excerpts-and-images.rst @@ -9,17 +9,14 @@ Post Excerpts and Images :exclude: :image: 2 - This post describes how to choose an excerpt and an image image for a post - to be displayed in archive pages. - + 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. +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:: @@ -27,26 +24,21 @@ Alternatively, you can provide some content in a post directive as follows:: 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:: +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. - + 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:: https://www.python.org/static/community_logos/python-logo.png - .. 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. +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 index c2022e36..cd87ebdc 100644 --- a/docs/manual/posting-and-listing.rst +++ b/docs/manual/posting-and-listing.rst @@ -7,15 +7,12 @@ Posting and Listing :location: Pittsburgh :author: Ahmet -This post describes :rst:dir:`post`, :rst:dir:`update`, and :rst:dir:`postlist` -directives. +This post describes :rst:dir:`post`, :rst:dir:`update`, and :rst:dir:`postlist` directives. Posting ------- -Any page in a Sphinx_ project can be converted to a post using the -following directive: - +Any page in a Sphinx_ project can be converted to a post using the following directive: .. rst:directive:: post @@ -31,48 +28,35 @@ following directive: :image: 1 :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 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. + 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. + 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. + 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. + 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. + 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. + 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. + 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** @@ -88,11 +72,10 @@ following directive: .. update:: 20 Apr, 2014 - Added :rst:dir:`update` directive and :ref:`posting-sections` - section. Also revised the text here and there. + 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 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. @@ -107,27 +90,18 @@ Posting Sections :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. +: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. +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. + * 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. + * 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 ------- @@ -150,11 +124,8 @@ A list of posts can be displayed in any page using the following directive: :excerpts: :sort: - 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:``. + 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 @@ -170,10 +141,8 @@ A list of posts can be displayed in any page using the following directive: :sort: - 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. - + 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 20, 2014 @@ -188,10 +157,9 @@ A list of posts can be displayed in any page using the following directive: .. update:: Mar 28, 2015 - Added ``:excerpts:`` option to :rst:dir:`postlist` to list posts - with their excerpts. + 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*, *disk*, and *none* (default) are recognized. + Added ``:list-style:`` option to :rst:dir:`postlist` to control bullet list style. + *circle*, *disk*, and *none* (default) are recognized. diff --git a/docs/manual/watch-yourself-blogging.rst b/docs/manual/watch-yourself-blogging.rst index 14cce176..84da97bc 100644 --- a/docs/manual/watch-yourself-blogging.rst +++ b/docs/manual/watch-yourself-blogging.rst @@ -9,15 +9,13 @@ Watch Yourself Blogging :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. +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. +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/release/ablog-v0.1-released.rst b/docs/release/ablog-v0.1-released.rst index 3f6bca65..37af5945 100644 --- a/docs/release/ablog-v0.1-released.rst +++ b/docs/release/ablog-v0.1-released.rst @@ -1,3 +1,4 @@ +:blogpost: true :tags: tips :author: Ahmet :category: Release @@ -7,7 +8,6 @@ ABlog v0.1 released =================== - ABlog v0.1 is released. This is the very first release, so there are no release notes in this post. diff --git a/docs/release/ablog-v0.10-released.rst b/docs/release/ablog-v0.10-released.rst index 49a151b3..c9005edf 100644 --- a/docs/release/ablog-v0.10-released.rst +++ b/docs/release/ablog-v0.10-released.rst @@ -6,18 +6,138 @@ ABlog v0.10 released :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: +Pull Requests merged in: + +`Overhaul of package underneath for python3 only `__ from `nabobalis `__. + +`Add validation for conf.py entries `__ from `rayalan `__. + +`Deploy improve `__ from `rayalan `__. + +`Get ablog ready for 0.10 `__ from `nabobalis `__. + +ABlog v0.10.1 released +---------------------- +.. post:: Dec 17, 2019 + :author: Nabil + :category: Release + :location: World + +Pull Requests merged in: + +`Change StopIteration to return `__ from `remyabel `__. + +ABlog v0.10.2 released +---------------------- +.. post:: Jan 2, 2020 + :author: Nabil + :category: Release + :location: World + +Pull Requests merged in: + +`Fix unclosed span tag `__ from `ykrods `__. + +ABlog v0.10.3 released +---------------------- +.. post:: Feb 12, 2020 + :author: Nabil + :category: Release + :location: World + +Pull Requests merged in: + +`Pin werkzeug to < 1 `__ from `dstansby `__. + +`MNT: Fix Giles URL `__ from `pllim `__. + +ABlog v0.10.4 released +---------------------- +.. post:: March 24, 2020 + :author: Nabil + :category: Release + :location: World + +Pull Requests merged in: + +`Add zh_CN locale `__ from `daimon99 `__. + +`Add intersphinx to the extension list `__ from `plaindocs `__. + +`Fix "test5" `__ and `Use "dirhtml" builder on Read The Docs `__ from `blueyed `__. + +ABlog v0.10.5 released +---------------------- +.. post:: Apr 18, 2020 + :author: Nabil + :category: Release + :location: World + +Pull Requests merged in: + +`Add custom GitHub URL support `__ from `tg-m `__. + +ABlog v0.10.6 released +---------------------- +.. post:: May 27, 2020 + :author: Nabil + :category: Release + :location: World + +Pull Requests merged in: + +`Add french locale `__ from `kujiu `__. + +ABlog v0.10.7 released +---------------------- +.. post:: Sept 7, 2020 + :author: Nabil + :category: Release + :location: World + +Pull Requests merged in: + +`Automatically add templates path to documentation `__ from `choldgraf `__. + +ABlog v0.10.8 released +---------------------- +.. post:: Sept 9, 2020 + :author: Nabil + :category: Release + :location: World + +Removed the hard dependencies on alabaster and sphinx-automodapi. + +Replaced `werkzeug `__ with `feedgen `__ due to the former removing ATOM support. + +Version pin of nbsphinx has been removed. + +ABlog v0.10.9 released +---------------------- +.. post:: Sept 16, 2020 + :author: Nabil + :category: Release + :location: World + +Pull Requests merged in: + +`frontmatter and blog post matching `__ from `choldgraf `__. + +ABlog v0.10.10 released +----------------------- +.. post:: Oct 10, 2020 + :author: Nabil + :category: Release + :location: World -`Overhaul of package underneath for python3 only `_ -from `nabobalis `_. +Pull Requests merged in: -`Add validation for conf.py entries `_ from `rayalan `_. +`Various Issues `__. -`Deploy improve `_ from `rayalan `_. +`Fix missing reference caused by ref with title `__ from `ykrods `__. -`Get ablog ready for 0.10 `_ from `nabobalis `_. +`Add instructions for starting new blog posts with front-matter `__ from `kakirastern `__. diff --git a/docs/release/ablog-v0.2-released.rst b/docs/release/ablog-v0.2-released.rst index 038afb3f..fc44b67f 100644 --- a/docs/release/ablog-v0.2-released.rst +++ b/docs/release/ablog-v0.2-released.rst @@ -6,7 +6,6 @@ ABlog v0.2 released :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` @@ -24,7 +23,6 @@ ABlog v0.2 is released. This version comes with several new features: * Recent posts side bar includes month and day of the posts. - ABlog v0.2.1 released --------------------- @@ -36,7 +34,6 @@ 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 --------------------- @@ -48,7 +45,6 @@ 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 --------------------- diff --git a/docs/release/ablog-v0.3-released.rst b/docs/release/ablog-v0.3-released.rst index 18b609f2..1cbc1660 100644 --- a/docs/release/ablog-v0.3-released.rst +++ b/docs/release/ablog-v0.3-released.rst @@ -6,7 +6,6 @@ ABlog v0.3 released :category: Release :location: SF - ABlog v0.3 is released. This version comes with the following core improvements: @@ -20,7 +19,6 @@ improvements: * :rst:dir:`postlist` directive takes options to filter posts. - ABlog v0.3.1 released --------------------- diff --git a/docs/release/ablog-v0.4-released.rst b/docs/release/ablog-v0.4-released.rst index 7509e347..605680f9 100644 --- a/docs/release/ablog-v0.4-released.rst +++ b/docs/release/ablog-v0.4-released.rst @@ -6,7 +6,6 @@ ABlog v0.4 released :category: Release :location: SF - ABlog v0.4 is released. This version comes with the following improvements and bug fixes: diff --git a/docs/release/ablog-v0.5-released.rst b/docs/release/ablog-v0.5-released.rst index dbbb5e82..610374c1 100644 --- a/docs/release/ablog-v0.5-released.rst +++ b/docs/release/ablog-v0.5-released.rst @@ -6,7 +6,6 @@ ABlog v0.5 released :category: Release :location: SF - ABlog v0.5 is released. This version comes with :ref:`ablog-commands` and a :ref:`quick-start` guide. diff --git a/docs/release/ablog-v0.6-released.rst b/docs/release/ablog-v0.6-released.rst index f9aa7e5f..a6f58ada 100644 --- a/docs/release/ablog-v0.6-released.rst +++ b/docs/release/ablog-v0.6-released.rst @@ -6,12 +6,10 @@ ABlog v0.6 released :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 --------------------- @@ -23,7 +21,6 @@ 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 --------------------- @@ -35,7 +32,6 @@ 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 --------------------- @@ -52,7 +48,6 @@ ABlog v0.6.3 comes with Russian localisation and following enhancements: * ``ablog post`` command de-slugifies filename to make the title when it's not given. - ABlog v0.6.4 released --------------------- @@ -64,7 +59,6 @@ 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 --------------------- diff --git a/docs/release/ablog-v0.7-released.rst b/docs/release/ablog-v0.7-released.rst index d7113bbd..476703a2 100644 --- a/docs/release/ablog-v0.7-released.rst +++ b/docs/release/ablog-v0.7-released.rst @@ -6,13 +6,11 @@ ABlog v0.7 released :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 --------------------- @@ -24,7 +22,6 @@ 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 --------------------- @@ -37,7 +34,6 @@ 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 --------------------- @@ -53,7 +49,6 @@ for this improvement. .. _python-dateutil: https://pypi.python.org/pypi/python-dateutil .. _Andy Maloney: https://github.com/amaloney - ABlog v0.7.5 released --------------------- @@ -65,7 +60,6 @@ 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 --------------------- @@ -84,7 +78,6 @@ to Peter Mills for reporting this issue. Other minor changes are: * ``conf.py`` file created by :ref:`ablog start ` updated to include ``about.html`` sidebar that comes with Alabaster_ theme. - ABlog v0.7.7 released --------------------- @@ -97,7 +90,6 @@ 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 --------------------- @@ -114,7 +106,6 @@ Thanks to `uralbash`_ for these contributions. .. _uralbash: https://github.com/uralbash - ABlog v0.7.9 released --------------------- @@ -129,7 +120,6 @@ for the fix. .. _Velimir: https://github.com/montyvesselinov - ABlog v0.7.10 released ---------------------- @@ -141,7 +131,6 @@ 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 ---------------------- diff --git a/docs/release/ablog-v0.8-released.rst b/docs/release/ablog-v0.8-released.rst index 35fbae10..c38e9bdf 100644 --- a/docs/release/ablog-v0.8-released.rst +++ b/docs/release/ablog-v0.8-released.rst @@ -6,7 +6,6 @@ ABlog v0.8 released :category: Release :location: SF - ABlog v0.8.0 is released with additions and changes: * Added ``-a`` argument to :ref:`ablog build ` command, with which @@ -35,8 +34,6 @@ ABlog v0.8.0 is released with additions and changes: .. _Albert Mietus: https://github.com/AlbertMietus .. _uralbash: https://github.com/uralbash - - ABlog v0.8.1 released --------------------- @@ -47,8 +44,6 @@ 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 --------------------- @@ -60,7 +55,6 @@ 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 --------------------- @@ -73,10 +67,7 @@ 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 index a6fdd435..6dee26f3 100644 --- a/docs/release/ablog-v0.9-released.rst +++ b/docs/release/ablog-v0.9-released.rst @@ -6,7 +6,6 @@ ABlog v0.9 released :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`_. @@ -14,25 +13,23 @@ This has merged in all current (at time of writing, 6) open PRs to the original These are: -`fix(commands): Update command arguments so patterns works correctly `_ -from `rayalan `_. - -`Fix couple of bugs with latest stable Sphinx `_ from `tadeboro `_. +`fix(commands): Update command arguments so patterns works correctly `__ from `rayalan `__. -`don't use fancy quotes in the conf.py template `_ from `tiwo `_. +`Fix couple of bugs with latest stable Sphinx `__ from `tadeboro `__. -`Pass through additional Sphinx options and fix a typo `_ from `ahrbel `_. +`don't use fancy quotes in the conf.py template `__ from `tiwo `__. -`fix #78 (ImportError: cannot import name make_admonition in Sphinx 1.6) `_ from `lsaffre `_. +`Pass through additional Sphinx options and fix a typo `__ from `ahrbel `__. -`Raise exception when title is missing `_ from `rgrinberg `_. +`fix #78 (ImportError: cannot import name make_admonition in Sphinx 1.6) `_ from `lsaffre `__. +`Raise exception when title is missing `__ from `rgrinberg `__. .. _Abakan: https://github.com/abakan/ablog .. _SunPy: https://github.com/sunpy/ablog ABlog v0.9.1 released -===================== +--------------------- .. post:: March 2, 2018 :author: Nabil @@ -42,17 +39,17 @@ ABlog v0.9.1 released Minor update to remove Ablog{}.format(python_number) exes ABlog v0.9.2 released -===================== +--------------------- .. post:: March 4, 2018 :author: Nabil :category: Release :location: World -Fixed Windows String issue +Fixed Windows String issue. ABlog v0.9.3 released -===================== +--------------------- .. post:: October 30, 2018 :author: Nabil @@ -60,4 +57,30 @@ ABlog v0.9.3 released :location: World Added example on how to use writing blog posts in Jupyter notebooks. -Several fixes provived by `anzawatta`, sorry I was late to release these! + +`show when if fa `__, `Add create file encoding `__ and `fix serve command path `__ from `anzawatta `__. + +Sorry I was late to release these! + +ABlog v0.9.4 released +--------------------- + +.. post:: Feb 10, 2019 + :author: Nabil + :category: Release + :location: World + +Fixes for gettext break and some pathing issues. + +ABlog v0.9.5 released +--------------------- + +.. post:: Aug 19, 2019 + :author: Nabil + :category: Release + :location: World + +v0.9.5 is the that supports Python 2 and Sphinx <2. +v0.10.0 on master now, will not. + +`Define an auto-orphan option `__, `Repair update directive `__ and `Fix sidebar and blog_baseurl misconfig during quick start `__ from `rayalan `__. diff --git a/setup.cfg b/setup.cfg index 2eedaff8..09981391 100644 --- a/setup.cfg +++ b/setup.cfg @@ -20,13 +20,15 @@ install_requires = feedgen invoke python-dateutil - sphinx>=2.0 + sphinx watchdog [options.extras_require] notebook = ipython nbsphinx +markdown = + myst-parser docs = alabaster sphinx-automodapi diff --git a/tox.ini b/tox.ini new file mode 100644 index 00000000..ce5f71ac --- /dev/null +++ b/tox.ini @@ -0,0 +1,74 @@ +[tox] +envlist = + py{36,37,38}-sphinx{2,3} + py{36,37,38}-devdeps + codestyle +isolated_build = true + +[testenv] +# We use bash in some of our enviroments so we have to whitelist it. +whitelist_externals= + /bin/bash + /usr/bin/bash + /bin/make + /usr/bin/make +# tox environments are constructued with so-called 'factors' (or terms) +# separated by hyphens, e.g. test-devdeps-cov. Lines below starting with factor: +# will only take effect if that factor is included in the environment name. To +# see a list of example environments that can be run, along with a description, +# run: +# +# tox -l -v +# +description = + run tests + devdeps: with the latest developer version of key dependencies +passenv = + HTTP_PROXY + HTTPS_PROXY + NO_PROXY + CIRCLECI +deps = + sphinx2: sphinx>=2.0,<3.0 + sphinx3: sphinx>=3.0,<4.0 + # The devdeps factor is intended to be used to install the latest developer version. + # of key dependencies. + devdeps: git+https://github.com/sphinx-doc/sphinx +# The following indicates which extras_require from setup.cfg will be installed +# dev is special in that it installs everything +extras = + all + docs +commands = + make tests + +[testenv:codestyle] +skip_install = true +description = Run all style and file checks with pre-commit +deps = + pre-commit +commands = + pre-commit install-hooks + pre-commit run --color always --verbose --all-files --show-diff-on-failure + +# This env requires tox-conda. +[testenv:py38-conda] +basepython = python3.8 +extras = +deps = +conda_deps = + alabaster + docutils + feedgen + invoke + ipython + myst-parser + nbsphinx + python-dateutil + sphinx + sphinx-automodapi + watchdog +conda_channels = conda-forge +install_command = pip install --no-deps {opts} {packages} +commands = + make tests