Add sphinx docs

README.md

@@ -4,16 +4,11 @@
 [github_license]: https://img.shields.io/github/license/sdispater/tomlkit.svg?logo=github&logoColor=white
 [github_action]: https://github.com/sdispater/tomlkit/actions/workflows/tests.yml/badge.svg
 
-<!--Codecov logo not offered by shields.io or simpleicons.org, this is Codecov's SVG image modified to be white-->
-
-[codecov]: https://img.shields.io/codecov/c/github/sdispater/tomlkit/master.svg?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iNTAiIGhlaWdodD0iNDgiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CgogPGc+CiAgPHRpdGxlPmJhY2tncm91bmQ8L3RpdGxlPgogIDxyZWN0IGZpbGw9Im5vbmUiIGlkPSJjYW52YXNfYmFja2dyb3VuZCIgaGVpZ2h0PSI0MDIiIHdpZHRoPSI1ODIiIHk9Ii0xIiB4PSItMSIvPgogPC9nPgogPGc+CiAgPHRpdGxlPkxheWVyIDE8L3RpdGxlPgogIDxwYXRoIGlkPSJzdmdfMSIgZmlsbC1ydWxlPSJldmVub2RkIiBmaWxsPSIjZmZmZmZmIiBkPSJtMjUuMDE0LDBjLTEzLjc4NCwwLjAxIC0yNS4wMDQsMTEuMTQ5IC0yNS4wMTQsMjQuODMybDAsMC4wNjJsNC4yNTQsMi40ODJsMC4wNTgsLTAuMDM5YTEyLjIzOCwxMi4yMzggMCAwIDEgOS4wNzgsLTEuOTI4YTExLjg0NCwxMS44NDQgMCAwIDEgNS45OCwyLjk3NWwwLjczLDAuNjhsMC40MTMsLTAuOTA0YzAuNCwtMC44NzQgMC44NjIsLTEuNjk2IDEuMzc0LC0yLjQ0M2MwLjIwNiwtMC4zIDAuNDMzLC0wLjYwNCAwLjY5MiwtMC45MjlsMC40MjcsLTAuNTM1bC0wLjUyNiwtMC40NGExNy40NSwxNy40NSAwIDAgMCAtOC4xLC0zLjc4MWExNy44NTMsMTcuODUzIDAgMCAwIC04LjM3NSwwLjQ5YzIuMDIzLC04Ljg2OCA5LjgyLC0xNS4wNSAxOS4wMjcsLTE1LjA1N2M1LjE5NSwwIDEwLjA3OCwyLjAwNyAxMy43NTIsNS42NTJjMi42MTksMi41OTggNC40MjIsNS44MzUgNS4yMjQsOS4zNzJhMTcuOTA4LDE3LjkwOCAwIDAgMCAtNS4yMDgsLTAuNzlsLTAuMzE4LC0wLjAwMWExOC4wOTYsMTguMDk2IDAgMCAwIC0yLjA2NywwLjE1M2wtMC4wODcsMC4wMTJjLTAuMzAzLDAuMDQgLTAuNTcsMC4wODEgLTAuODEzLDAuMTI2Yy0wLjExOSwwLjAyIC0wLjIzNywwLjA0NSAtMC4zNTUsMC4wNjhjLTAuMjgsMC4wNTcgLTAuNTU0LDAuMTE5IC0wLjgxNiwwLjE4NWwtMC4yODgsMC4wNzNjLTAuMzM2LDAuMDkgLTAuNjc1LDAuMTkxIC0xLjAwNiwwLjNsLTAuMDYxLDAuMDJjLTAuNzQsMC4yNTEgLTEuNDc4LDAuNTU4IC0yLjE5LDAuOTE0bC0wLjA1NywwLjAyOWMtMC4zMTYsMC4xNTggLTAuNjM2LDAuMzMzIC0wLjk3OCwwLjUzNGwtMC4wNzUsMC4wNDVhMTYuOTcsMTYuOTcgMCAwIDAgLTQuNDE0LDMuNzhsLTAuMTU3LDAuMTkxYy0wLjMxNywwLjM5NCAtMC41NjcsMC43MjcgLTAuNzg3LDEuMDQ4Yy0wLjE4NCwwLjI3IC0wLjM2OSwwLjU2IC0wLjYsMC45NDJsLTAuMTI2LDAuMjE3Yy0wLjE4NCwwLjMxOCAtMC4zNDgsMC42MjIgLTAuNDg3LDAuOWwtMC4wMzMsMC4wNjFjLTAuMzU0LDAuNzExIC0wLjY2MSwxLjQ1NSAtMC45MTcsMi4yMTRsLTAuMDM2LDAuMTExYTE3LjEzLDE3LjEzIDAgMCAwIC0wLjg1NSw1LjY0NGwwLjAwMywwLjIzNGEyMy41NjUsMjMuNTY1IDAgMCAwIDAuMDQzLDAuODIyYzAuMDEsMC4xMyAwLjAyMywwLjI1OSAwLjAzNiwwLjM4OGMwLjAxNSwwLjE1OCAwLjAzNCwwLjMxNiAwLjA1MywwLjQ3MWwwLjAxMSwwLjA4OGwwLjAyOCwwLjIxNGMwLjAzNywwLjI2NCAwLjA4LDAuNTI1IDAuMTMsMC43ODdjMC41MDMsMi42MzcgMS43Niw1LjI3NCAzLjYzNSw3LjYyNWwwLjA4NSwwLjEwNmwwLjA4NywtMC4xMDRjMC43NDgsLTAuODg0IDIuNjAzLC0zLjY4NyAyLjc2LC01LjM2OWwwLjAwMywtMC4wMzFsLTAuMDE1LC0wLjAyOGExMS43MzYsMTEuNzM2IDAgMCAxIC0xLjMzMywtNS40MDdjMCwtNi4yODQgNC45NCwtMTEuNTAyIDExLjI0MywtMTEuODhsMC40MTQsLTAuMDE1YzIuNTYxLC0wLjA1OCA1LjA2NCwwLjY3MyA3LjIzLDIuMTM2bDAuMDU4LDAuMDM5bDQuMTk3LC0yLjQ0bDAuMDU1LC0wLjAzM2wwLC0wLjA2MmMwLjAwNiwtNi42MzIgLTIuNTkyLC0xMi44NjUgLTcuMzE0LC0xNy41NTFjLTQuNzE2LC00LjY3OSAtMTAuOTkxLC03LjI1NSAtMTcuNjcyLC03LjI1NSIvPgogPC9nPgo8L3N2Zz4=&label=Codecov
-
 [![GitHub Release][github_release]](https://github.com/sdispater/tomlkit/releases/)
-[![PyPI Version][pypi_version]](https://pypi.python.org/pypi/tomlkit/)
-[![Python Versions][python_versions]](https://pypi.python.org/pypi/tomlkit/)
+[![PyPI Version][pypi_version]](https://pypi.org/project/tomlkit/)
+[![Python Versions][python_versions]](https://pypi.org/project/tomlkit/)
 [![License][github_license]](https://github.com/sdispater/tomlkit/blob/master/LICENSE)
 <br>
-[![Codecov][codecov]](https://codecov.io/gh/sdispater/tomlkit)
 [![Tests][github_action]](https://github.com/sdispater/tomlkit/actions/workflows/tests.yml)
 
 # TOML Kit - Style-preserving TOML library for Python
@@ -29,128 +24,7 @@ Part of the implementation as been adapted, improved and fixed from [Molten](htt
 
 ## Usage
 
-### Parsing
-
-TOML Kit comes with a fast and style-preserving parser to help you access
-the content of TOML files and strings.
-
-```python
->>> from tomlkit import dumps
->>> from tomlkit import parse  # you can also use loads
-
->>> content = """[table]
-... foo = "bar"  # String
-... """
->>> doc = parse(content)
-
-# doc is a TOMLDocument instance that holds all the information
-# about the TOML string.
-# It behaves like a standard dictionary.
-
->>> assert doc["table"]["foo"] == "bar"
-
-# The string generated from the document is exactly the same
-# as the original string
->>> assert dumps(doc) == content
-```
-
-### Modifying
-
-TOML Kit provides an intuitive API to modify TOML documents.
-
-```python
->>> from tomlkit import dumps
->>> from tomlkit import parse
->>> from tomlkit import table
-
->>> doc = parse("""[table]
-... foo = "bar"  # String
-... """)
-
->>> doc["table"]["baz"] = 13
-
->>> dumps(doc)
-"""[table]
-foo = "bar"  # String
-baz = 13
-"""
-
-# Add a new table
->>> tab = table()
->>> tab.add("array", [1, 2, 3])
-
->>> doc["table2"] = tab
-
->>> dumps(doc)
-"""[table]
-foo = "bar"  # String
-baz = 13
-
-[table2]
-array = [1, 2, 3]
-"""
-
-# Remove the newly added table
->>> doc.remove("table2")
-# del doc["table2] is also possible
-```
-
-### Writing
-
-You can also write a new TOML document from scratch.
-
-Let's say we want to create this following document:
-
-```toml
-# This is a TOML document.
-
-title = "TOML Example"
-
-[owner]
-name = "Tom Preston-Werner"
-organization = "GitHub"
-bio = "GitHub Cofounder & CEO\nLikes tater tots and beer."
-dob = 1979-05-27T07:32:00Z # First class dates? Why not?
-
-[database]
-server = "192.168.1.1"
-ports = [ 8001, 8001, 8002 ]
-connection_max = 5000
-enabled = true
-```
-
-It can be created with the following code:
-
-```python
->>> from tomlkit import comment
->>> from tomlkit import document
->>> from tomlkit import nl
->>> from tomlkit import table
-
->>> doc = document()
->>> doc.add(comment("This is a TOML document."))
->>> doc.add(nl())
->>> doc.add("title", "TOML Example")
-# Using doc["title"] = "TOML Example" is also possible
-
->>> owner = table()
->>> owner.add("name", "Tom Preston-Werner")
->>> owner.add("organization", "GitHub")
->>> owner.add("bio", "GitHub Cofounder & CEO\nLikes tater tots and beer.")
->>> owner.add("dob", datetime(1979, 5, 27, 7, 32, tzinfo=utc))
->>> owner["dob"].comment("First class dates? Why not?")
-
-# Adding the table to the document
->>> doc.add("owner", owner)
-
->>> database = table()
->>> database["server"] = "192.168.1.1"
->>> database["ports"] = [8001, 8001, 8002]
->>> database["connection_max"] = 5000
->>> database["enabled"] = True
-
->>> doc["database"] = database
-```
+See the [documentation](https://tomlkit.readthedocs.io/en/latest/quickstart.html) for more information.
 
 ## Installation
 

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/api.rst

@@ -0,0 +1,43 @@
+API Reference
+=============
+
+Public API
+----------
+
+Functions you need to create TOML elements to construct
+a TOML document.
+
+.. automodule:: tomlkit
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+TOML Document
+-------------
+
+.. module:: tomlkit.toml_document
+
+.. autoclass:: TOMLDocument
+   :show-inheritance:
+   :inherited-members:
+
+
+TOML File
+---------
+
+.. module:: tomlkit.toml_file
+
+.. autoclass:: TOMLFile
+   :show-inheritance:
+   :members:
+
+
+TOML Items
+----------
+
+.. module:: tomlkit.items
+
+.. automodule:: tomlkit.items
+   :show-inheritance:
+   :members:
+   :exclude-members: item, AbstractTable

docs/conf.py

@@ -0,0 +1,60 @@
+# 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.dirname(os.path.dirname(__file__)))
+
+from tomlkit import __version__  # noqa: E402
+
+
+# -- Project information -----------------------------------------------------
+
+project = "TOML Kit"
+copyright = "2021, Sébastien Eustace"
+author = "Sébastien Eustace"
+
+# The full version, including alpha/beta/rc tags
+release = __version__
+
+
+# -- 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 = [
+    "sphinx.ext.autodoc",
+]
+
+# 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 = "furo"
+
+# 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/index.rst

@@ -0,0 +1,57 @@
+.. TOMLKit documentation master file, created by
+   sphinx-quickstart on Fri Dec 24 09:31:46 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+TOML Kit
+========
+
+    **Style-preserving TOML library for Python**
+
+.. image:: https://img.shields.io/pypi/v/tomlkit.svg?logo=python&logoColor=white
+    :target: https://pypi.org/project/tomlkit/
+.. image:: https://img.shields.io/pypi/pyversions/tomlkit.svg?logo=python&logoColor=white
+    :target: https://pypi.org/project/tomlkit/
+.. image:: https://img.shields.io/github/license/sdispater/tomlkit.svg?logo=github&logoColor=white
+   :target: https://github.com/sdispater/tomlkit/blob/master/LICENSE
+.. image:: https://img.shields.io/badge/TOML-1.0.0-9c4221
+   :target: https://toml.io/en/v1.0.0
+
+TOML Kit is a **1.0.0-compliant** `TOML <https://toml.io/>`_ library.
+
+It includes a parser that preserves all comments, indentations, whitespace and internal element ordering,
+and makes them accessible and editable via an intuitive API.
+
+You can also create new TOML documents from scratch using the provided helpers.
+
+Part of the implementation as been adapted, improved and fixed from `Molten <https://github.com/LeopoldArkham/Molten>`_.
+
+Installation
+------------
+
+If you are using `Poetry <https://poetry.eustace.io>`_,
+add ``tomlkit`` to your ``pyproject.toml`` file by using::
+
+    poetry add tomlkit
+
+If not, you can use ``pip``::
+
+    pip install tomlkit
+
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   quickstart
+   api
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd