From 71b99063960925d30c02da3a95bb4072e055f8a8 Mon Sep 17 00:00:00 2001 From: Nabil Freij Date: Fri, 6 Sep 2024 12:23:28 -0400 Subject: [PATCH] docs --- .pre-commit-config.yaml | 4 +- docs/conf.py | 40 +--- docs/index.rst | 99 +--------- docs/manual/ablog-commands.rst | 178 ------------------ docs/manual/api.rst | 13 +- docs/manual/commands.rst | 61 ++++++ ...-options.rst => configuration-options.rst} | 2 +- docs/manual/{ablog-i18n.rst => i18n.rst} | 0 docs/manual/index.rst | 11 ++ docs/manual/installation.rst | 19 ++ ...{ablog-quick-start.rst => quick-start.rst} | 2 +- docs/release/index.rst | 11 ++ 12 files changed, 124 insertions(+), 316 deletions(-) delete mode 100644 docs/manual/ablog-commands.rst create mode 100644 docs/manual/commands.rst rename docs/manual/{ablog-configuration-options.rst => configuration-options.rst} (99%) rename docs/manual/{ablog-i18n.rst => i18n.rst} (100%) create mode 100644 docs/manual/index.rst create mode 100644 docs/manual/installation.rst rename docs/manual/{ablog-quick-start.rst => quick-start.rst} (98%) create mode 100644 docs/release/index.rst diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8b959bc2..c78eddf0 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -19,7 +19,7 @@ repos: ] exclude: ".*(.fits|.fts|.fit|.txt|tca.*|extern.*|.rst|.md|docs/conf.py)$" - repo: https://github.com/astral-sh/ruff-pre-commit - rev: "v0.5.0" + rev: "v0.6.4" hooks: - id: ruff args: ["--fix", "--unsafe-fixes"] @@ -48,7 +48,7 @@ repos: hooks: - id: prettier - repo: https://github.com/Riverside-Healthcare/djLint - rev: v1.34.1 + rev: v1.35.2 hooks: - id: djlint-jinja types_or: ["html"] diff --git a/docs/conf.py b/docs/conf.py index ad4463ca..ca1249c8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,8 +1,7 @@ -import re +import datetime from pathlib import Path from packaging.version import parse as _parse -from sphinx import addnodes import ablog @@ -16,6 +15,7 @@ "sphinx.ext.ifconfig", "sphinx.ext.extlinks", "sphinx_automodapi.automodapi", + "sphinx_toolbox", "ablog", "alabaster", "nbsphinx", @@ -24,7 +24,8 @@ version = str(_parse(ablog.__version__)) project = "ABlog" -copyright = "2014-2022, ABlog Team" +current_year = datetime.datetime.now().year +copyright = f"2014-{current_year}, ABlog Team" # NOQA: A001 master_doc = "index" source_suffix = { ".rst": "restructuredtext", @@ -90,6 +91,8 @@ "description": "ABlog for blogging with Sphinx", "logo": "ablog.png", } +github_username = "sunpy" +github_repository = "ablog" intersphinx_mapping = { "python": ("https://docs.python.org/", None), "sphinx": ("https://www.sphinx-doc.org/en/master/", None), @@ -117,34 +120,3 @@ 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 index 407451f9..884a9df9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,8 @@ -ABlog for Sphinx -================ +.. _ablog-index: + +**************************** +ABlog - Blogging with Sphinx +**************************** ABlog is a Sphinx extension that converts any documentation or personal website project into a full-fledged blog with: @@ -10,95 +13,9 @@ ABlog is a Sphinx extension that converts any documentation or personal website * :ref:`Font-Awesome integration ` * :doc:`manual/markdown` -Ablog is part of the `SunPy Project `__. - -.. _installation: - -Installation ------------- - -You can install ABlog using `pip `__:: - - pip install -U ablog - -or `miniforge `__:: - - conda install ablog - -This will also install `Sphinx `__, `feedgen `__, and `Invoke `__ 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 +Ablog is currently maintained by the `The SunPy Project `__. .. toctree:: - :hidden: - :glob: - */* + release/index + manual/index diff --git a/docs/manual/ablog-commands.rst b/docs/manual/ablog-commands.rst deleted file mode 100644 index c50cbd7d..00000000 --- a/docs/manual/ablog-commands.rst +++ /dev/null @@ -1,178 +0,0 @@ -.. _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 -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/api.rst b/docs/manual/api.rst index 9704c3cb..58c9cf52 100644 --- a/docs/manual/api.rst +++ b/docs/manual/api.rst @@ -1,13 +1,8 @@ -.. api: +.. _ablog_manual_api: -ABlog API -========= - -.. post:: Feb 17, 2018 - :tags: api - :author: Nabil Freij - :category: Manual - :location: World +*** +API +*** .. automodapi:: ablog diff --git a/docs/manual/commands.rst b/docs/manual/commands.rst new file mode 100644 index 00000000..65490762 --- /dev/null +++ b/docs/manual/commands.rst @@ -0,0 +1,61 @@ +.. _ablog_manual_commands: + +************** +ABlog Commands +************** + +``ablog`` has commands for streamlining blog operations, i.e., building, serving, and viewing blog pages, as well as starting a new blog: + +.. code-block:: bash + + $ ablog + usage: ablog [-h] [-v] {start,build,clean,serve,post,deploy} ... + + ABlog for blogging with Sphinx + + options: + -h, --help show this help message and exit + -v, --version print ABlog version and exit + + commands: + {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 -h' for more information on a specific command. + +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. + +Build your Website +================== + +Running ``ablog build`` in your project folder builds your website HTML pages. + +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. + + +Deploy to GitHub Pages +====================== + +Running ``ablog deploy`` will push your website to GitHub. + +Create a Post +============= + +Running ``ablog post`` will make a new post template file. + +Clean Build Files +================= + +In case you needed, running ``ablog clean`` will remove build files and do a deep clean with ``-D`` option. diff --git a/docs/manual/ablog-configuration-options.rst b/docs/manual/configuration-options.rst similarity index 99% rename from docs/manual/ablog-configuration-options.rst rename to docs/manual/configuration-options.rst index f24e50e6..2bc40f13 100644 --- a/docs/manual/ablog-configuration-options.rst +++ b/docs/manual/configuration-options.rst @@ -291,7 +291,7 @@ Command Options .. update:: Apr 7, 2015 - Added :ref:`commands` options. + Added :ref:`ablog_manual_commands` options. .. confval:: ablog_website diff --git a/docs/manual/ablog-i18n.rst b/docs/manual/i18n.rst similarity index 100% rename from docs/manual/ablog-i18n.rst rename to docs/manual/i18n.rst diff --git a/docs/manual/index.rst b/docs/manual/index.rst new file mode 100644 index 00000000..e3376754 --- /dev/null +++ b/docs/manual/index.rst @@ -0,0 +1,11 @@ +.. _ablog_manual-index: + +************ +ABlog Manual +************ + +.. toctree:: + :maxdepth: 2 + :glob: + + * diff --git a/docs/manual/installation.rst b/docs/manual/installation.rst new file mode 100644 index 00000000..0ee69e83 --- /dev/null +++ b/docs/manual/installation.rst @@ -0,0 +1,19 @@ +.. _ablog-installation: + +************ +Installation +************ + +You can install ABlog using `pip `__: + +.. code-block:: bash + + $ pip install -U ablog + +or `conda-forge `__: + +.. code-block:: bash + + $ conda install ablog + +This will install ABlog and its dependencies. diff --git a/docs/manual/ablog-quick-start.rst b/docs/manual/quick-start.rst similarity index 98% rename from docs/manual/ablog-quick-start.rst rename to docs/manual/quick-start.rst index 128bb597..96b03c3d 100644 --- a/docs/manual/ablog-quick-start.rst +++ b/docs/manual/quick-start.rst @@ -35,7 +35,7 @@ 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. +See :ref:`ablog_manual_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. diff --git a/docs/release/index.rst b/docs/release/index.rst new file mode 100644 index 00000000..880dab75 --- /dev/null +++ b/docs/release/index.rst @@ -0,0 +1,11 @@ +.. _ablog_release-index: + +********************* +ABlog Release History +********************* + +.. toctree:: + :maxdepth: 1 + :glob: + + *