add docs folder for readthedocs

.gitignore

@@ -16,7 +16,7 @@ aaa\.Rmd*
 # compiled object files
 *.o
 *.so
-docs
+docs/_build
 inst/bin
 inst/WORDLIST
 windows

.readthedocs.yaml

@@ -0,0 +1,36 @@
+# .readthedocs.yaml
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+   - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/requirements.txt

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: r2readthedocs
 Title: Convert R Package Documentation to a 'readthedocs' Website
-Version: 0.0.1.030
+Version: 0.0.1.031
 Authors@R: 
     person("Mark", "Padgham", , "[email protected]", role = c("aut", "cre"))
 Description: Convert R package documentation to a 'readthedocs' website.

codemeta.json

@@ -7,7 +7,7 @@
   "codeRepository": "https://github.com/ropenscilabs/r2readthedocs",
   "issueTracker": "https://github.com/ropenscilabs/r2readthedocs/issues",
   "license": "https://spdx.org/licenses/GPL-3.0",
-  "version": "0.0.1.030",
+  "version": "0.0.1.031",
   "programmingLanguage": {
     "@type": "ComputerLanguage",
     "name": "R",

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,69 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'r2readthedocs'
+copyright = '2022, Mark Padgham'
+author = 'Mark Padgham'
+
+# The full version, including alpha/beta/rc tags
+release = '0.0.1'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'myst_parser',
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+]
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}
+intersphinx_disabled_domains = ['std']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+#html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/functions/r2readthedocs-package.md

@@ -0,0 +1,23 @@
+# `r2readthedocs-package`
+
+r2readthedocs: Convert R Package Documentation to a 'readthedocs' Website
+
+
+## Description
+
+Convert R package documentation to a 'readthedocs' website.
+
+
+## Seealso
+
+Useful links:
+
+
+*   [https://github.com/ropenscilabs/r2readthedocs](https://github.com/ropenscilabs/r2readthedocs)   
+
+*  Report bugs at [https://github.com/ropenscilabs/r2readthedocs/issues](https://github.com/ropenscilabs/r2readthedocs/issues)
+
+
+## Author
+
+Maintainer : Mark Padgham [email protected]

docs/functions/r2readthedocs.md

@@ -0,0 +1,29 @@
+# `r2readthedocs`
+
+Convert package documentation to `readthedocs` format
+
+
+## Description
+
+Convert package documentation to `readthedocs` format
+
+
+## Usage
+
+```r
+r2readthedocs(path = here::here(), dev = FALSE, open = TRUE)
+```
+
+
+## Arguments
+
+Argument      |Description
+------------- |----------------
+`path`     |     Path to local R package with documentation to be converted
+`dev`     |     If `TRUE` , include function documentation of all dependency packages in site.
+`open`     |     If `TRUE` , open the documentation site in default browser.
+
+
+## Value
+
+TRUE (invisibly) if documentation successfully converted.

docs/functions/rtd_build.md

@@ -0,0 +1,23 @@
+# `rtd_build`
+
+Build the RTD site
+
+
+## Description
+
+Build the RTD site
+
+
+## Usage
+
+```r
+rtd_build(path = ".", dev = FALSE)
+```
+
+
+## Arguments
+
+Argument      |Description
+------------- |----------------
+`path`     |     Path to local R package with documentation to be converted
+`dev`     |     If `TRUE` , include function documentation of all dependency packages in site.

docs/functions/rtd_clean.md

@@ -0,0 +1,23 @@
+# `rtd_clean`
+
+Clean the RTD _build directory
+
+
+## Description
+
+Clean the RTD _build directory
+
+
+## Usage
+
+```r
+rtd_clean(path = ".", full = FALSE)
+```
+
+
+## Arguments
+
+Argument      |Description
+------------- |----------------
+`path`     |     Path to local R package with documentation to be converted
+`full`     |     If `TRUE` , also clean R package files, including vignettes and help files. Use [r2readthedocs](#r2readthedocs) to re-generate these.

docs/functions/rtd_dummy_pkg.md

@@ -0,0 +1,28 @@
+# `rtd_dummy_pkg`
+
+Make a dummy package for testing 'r2readthedocs' functions
+
+
+## Description
+
+Make a dummy package for testing 'r2readthedocs' functions
+
+
+## Usage
+
+```r
+rtd_dummy_pkg(base_dir = tempdir(), pkg_name = "demo")
+```
+
+
+## Arguments
+
+Argument      |Description
+------------- |----------------
+`base_dir`     |     Base directory in which package is to be constructed (as a sub-directory)
+`pkg_name`     |     Name of package, which will become a sub-directory of `base_dir` .
+
+
+## Value
+
+Path to root directory of resultant package

docs/functions/rtd_open.md

@@ -0,0 +1,22 @@
+# `rtd_open`
+
+Open the main RTD 'html' page in default browser
+
+
+## Description
+
+Open the main RTD 'html' page in default browser
+
+
+## Usage
+
+```r
+rtd_open(path = ".")
+```
+
+
+## Arguments
+
+Argument      |Description
+------------- |----------------
+`path`     |     Path to local R package with documentation to be converted

docs/index.rst

@@ -0,0 +1,87 @@
+.. documentation master file, created by sphinx-quickstart 
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+reStructuredText
+================================
+
+.. raw:: html
+
+    <style> .red {color:red} </style>
+
+.. role:: red
+
+This main document is in `'reStructuredText' ("rst") format
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_,
+which differs in many ways from standard markdown commonly used in R packages.
+``rst`` is richer and more powerful than markdown. The remainder of this main
+document demonstrates some of the features, with links to additional ``rst``
+documentation to help you get started. The definitive argument for the benefits
+of ``rst`` over markdown is the `official language format documentation
+<https://www.python.org/dev/peps/pep-0287/>`_, which starts with a very clear
+explanation of the `benefits
+<https://www.python.org/dev/peps/pep-0287/#benefits>`_.
+
+Examples
+--------
+
+All of the following are defined within the ``docs/index.rst`` file. Here is
+some :red:`coloured` text which demonstrates how raw HTML commands can be
+incorporated. The following are examples of ``rst`` "admonitions":
+
+.. note::
+
+    Here is a note
+
+    .. warning::
+
+        With a warning inside the note
+
+.. seealso::
+
+    The full list of `'restructuredtext' directives <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`_ or a similar list of `admonitions <https://restructuredtext.documatt.com/admonitions.html>`_.
+
+.. centered:: This is a line of :red:`centered text`
+
+.. hlist::
+   :columns: 3
+
+   * and here is
+   * A list of
+   * short items
+   * that are
+   * displayed
+   * in 3 columns
+
+The remainder of this document shows three tables of contents for the main
+``README`` (under "Introduction"), and the vignettes and R directories of
+a package. These can be restructured any way you like by changing the main
+``docs/index.rst`` file. The contents of this file -- and indeed the contents
+of any `readthedocs <https://readthedocs.org>`_ file -- can be viewed by
+clicking *View page source* at the top left of any page.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Introduction:
+
+   r2readthedocs.md
+
+
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Vignettes
+
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Functions
+
+   functions/r2readthedocs-package.md
+   functions/r2readthedocs.md
+   functions/rtd_build.md
+   functions/rtd_clean.md
+   functions/rtd_dummy_pkg.md
+   functions/rtd_open.md