mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2024-11-19 01:43:36 +01:00
Code Issues Projects Releases Wiki Activity

remove mkdocs and sphinx files

Browse Source
This commit is contained in:
Adi Shankara 2023-07-14 15:09:08 +04:00 committed by Rusty Russell
parent 9e47c16021
commit 4e46cdba93
9 changed files with 0 additions and 510 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

246
doc/conf.py
View File

@ -1,246 +0,0 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# core-lightning documentation build configuration file, created by
# sphinx-quickstart on Thu Feb 1 00:24:47 2018.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# 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('.'))
from datetime import datetime
import subprocess
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# 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.mathjax',
'sphinx.ext.githubpages',
'sphinx.ext.graphviz',
'sphinx.ext.autodoc',
'recommonmark',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = ['.rst', '.md']
# The encoding of source files.
#
# source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'core-lightning'
author = 'Core Lightning Developers'
copyright = datetime.now().strftime('2015 — %Y, {}'.format(author))
# 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.
#
# The short X.Y version.
version = subprocess.check_output('git describe --always --dirty=-modded --abbrev=7'.split()).decode('ASCII')
# The full version, including alpha/beta/rc tags.
release = version
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'en'
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#
# today = ''
#
# Else, today_fmt is used as the format for a strftime call.
#
today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'release-notes']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#
# show_authors = False
# The name of the Pygments style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- 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 = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []
# The name for this set of Sphinx documents.
# "<project> v<release> documentation" by default.
#
html_title = 'Core Lightning ' + version
# A shorter title for the navigation bar. Default is the same as html_title.
#
html_short_title = html_title
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#
# html_logo = None
# The name of an image file (relative to this directory) to use as a favicon of
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#
# html_favicon = None
# 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']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#
# html_extra_path = []
# If not None, a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
# The empty string is equivalent to '%b %d, %Y'.
#
html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#
# html_additional_pages = {}
# If false, no module index is generated.
#
# html_domain_indices = True
# If false, no index is generated.
#
# html_use_index = True
# If true, the index is split into individual pages for each letter.
#
# html_split_index = False
# If true, links to the reST sources are added to the pages.
#
html_show_sourcelink = False
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh'
#
# html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change `jieba` dictionary path.
#
# html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#
# html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'core-lightningdoc'

138
doc/dev/contributors/codegen.md
View File

@ -1,138 +0,0 @@
# Code Generation
The CLN project has a multitude of interfaces, most of which are
generated from an abstract schema:
- Wire format for peer-to-peer communication: this is the binary
format that is specific by the [LN spec][spec]. It uses the
[generate-wire.py][generate-wire.py] script to parse the (faux) CSV
files that are automatically extrated from the specification and
writes C source code files that are then used internally to encode
and decode messages, as well as provide print functions for the
messages.
- Wire format for inter-daemon communication: CLN follows a
multi-daemon architecture, making communication explicit across
daemons. For this inter-daemon communication we use a slightly
altered message format from the [LN spec][spec]. The changes are 1)
addition of FD passing semantics to allow establishing a new
connection between daemons (communication uses
[socketpair][socketpair]s, so no `connect`), and 2) change the
message length prefix from `u16` to `u32`, allowing for messages
larger than 65Kb. The CSV files are with the respective sub-daemon
and also use [generate-wire.py][generate-wire.py] to generate
encoding, decoding and printing functions.
- We describe the JSON-RPC using [JSON Schema][jschema] in the
[`doc/schemas`][doc-schemas] directory. Each method has a
`.request.json` for the request message, and a `.schema.json` for
the response (the mismatch is historical and will eventually be
addressed). During tests the `pytest` target will verify responses,
however the JSON-RPC methods are _not_ generated (yet?). We do
generate various client stubs for languages, using the
[`msggen`][msggen] tool. More on the generated stubs and utilities
below.
## Man pages
The [manpages][man] are partially generated from the JSON schemas
using the [`fromschema`][fromschema] tool. It reads the request schema
and fills in the manpage between two markers:
```markdown
[comment]: # (GENERATE-FROM-SCHEMA-START)
...
[comment]: # (GENERATE-FROM-SCHEMA-END)
```
!!! note
Some of this functionality overlaps with [`msggen`][msggen] (parsing the Schemas)
and [blockreplace.py][blockreplace.py] (filling in the template). It
is likely that this will eventually be merged.
[blockreplace.py]: https://github.com/ElementsProject/lightning/blob/master/devtools/blockreplace.py
[man]: ../../reference/
[fromschema]: https://github.com/ElementsProject/lightning/blob/master/tools/fromschema.py
## `msggen`
`msggen` is used to generate JSON-RPC client stubs, and converters
between in-memory formats and the JSON format. In addition, by
chaining some of these we can expose a [grpc][grpc] interface that
matches the JSON-RPC interface. This conversion chain is implemented
in the [grpc-plugin][grpc-plugin]
<figure markdown>
```mermaid
graph LR
A[JSON schema];
A --> B[cln-rpc];
B --> B1[Request Structs];
B --> B2[Response Structs];
B --> B3[Method stubs];
A --> C[cln-grpc];
C --> C1[Protobuf File];
C --> C2[In-memory conversion];
C --> C3[Service Implementation];
```
<figcaption>Artifacts generated from the JSON Schemas using `msggen`</figcaption>
</figure>
### `cln-rpc`
We use `msggen` to generate the Rust bindings crate
[`cln-rpc`][cln-rpc]. These bindings contain the stubs for the
JSON-RPC methods, as well as types for the request and response
structs. The [generator code][cln-rpc-gen] maps each abstract JSON-RPC
type to a Rust type, minimizing size (e.g., binary data is
hex-decoded).
The calling pattern follows the `call(req_obj) -> resp_obj` format,
and the individual arguments are not expanded. For more ergonomic
handling of generic requests and responses we also define the
`Request` and `Response` enumerations, so you can hand them to a
generic function without having to resort to dynamic dispatch.
The remainder of the crate implements an async/await JSON-RPC client,
that can deal with the Unix Domain Socket [transport][man:json-rpc]
used by CLN.
### `cln-grpc`
The `cln-grpc` crate is mostly used to provide the primitives to build
the `grpc-plugin`. As mentioned above, the grpc functionality relies on a chain of generated parts:
- First `msggen` is used to generate the [protobuf file][proto],
containing the service definition with the method stubs, and the types
referenced by those stubs.
- Next it generates the `convert.rs` file which is used to convert
the structs for in-memory representation from `cln-rpc` into the
corresponding protobuf structs.
- Finally `msggen` generates the `server.rs` file which can be bound
to a grpc endpoint listening for incoming grpc requests, and it
will convert the request and forward it to the JSON-RPC. Upon
receiving the response it gets converted back into a grpc response
and sent back.
```mermaid
graph LR
A[grpc client] --> B[grpc server] -->|convert.rs| C[cln-rpc] --> D[lightningd];
D --> C -->|convert.rs| B --> A;
```
[proto]: https://github.com/ElementsProject/lightning/blob/master/cln-grpc/proto/node.proto
[man:json-rpc]: ../../lightningd-rpc.7.md
[cln-rpc-gen]: https://github.com/ElementsProject/lightning/blob/master/contrib/msggen/msggen/gen/rust.py
[spec]: https://github.com/lightning/bolts
[generate-wire.py]: https://github.com/ElementsProject/lightning/blob/master/tools/generate-wire.py
[socketpair]: https://man7.org/linux/man-pages/man2/socketpair.2.html
[jschema]: https://json-schema.org/
[doc-schemas]: https://github.com/ElementsProject/lightning/tree/master/doc/schemas
[msggen]: https://github.com/ElementsProject/lightning/tree/master/contrib/msggen
[grpc]: https://grpc.io/
[cln-grpc]: https://docs.rs/cln-grpc/0.1.1/cln_grpc/
[grpc-plugin]: https://github.com/ElementsProject/lightning/tree/master/plugins/grpc-plugin
[cln-rpc]: https://github.com/ElementsProject/lightning/tree/master/cln-rpc

1
doc/dev/contributors/index.md
View File

@ -1 +0,0 @@
# Developer Documentation

1
doc/dev/index.md
View File

@ -1 +0,0 @@
# Developer Documentation

10
doc/index.md
View File

@ -1,10 +0,0 @@
Core Lightning (previously c-lightning) is a lightweight, highly
customizable and [standard compliant][std] implementation of the
Lightning Network protocol.
This documentation site will walk you through your first steps, teach
you how to develop on top of CLN and act as a reference for veteran
programmers.
[std]: https://github.com/lightning/bolts

1
doc/reference/index.md
View File

@ -1 +0,0 @@
# Core-Lightning References

109
doc/release-notes/release-0.6.md
View File

@ -1,109 +0,0 @@
# Release Announce for 0.6
## a.k.a. "I Accidentally The Smart Contract"
The long wait is over: the c-lightning team is excited to announce the 0.6 release of
[c-lightning][clightning], an important milestone for the project. This complete rewrite of the previous implementation is the first fully specification-compliant release of c-lightning. It migrates away from the protocol used while designing the specification and toward a new architecture that is modular and extensible, to better adapt to your needs and your infrastructure.
## New Features
While there are far too many new features in the 0.6 release to list, the following are the most interesting and impactful:
- __Lightweight nodes__: Previous releases required a full `bitcoind` node
running alongside c-lightning, to provide access to the Bitcoin network. This release still requires the `bitcoin-cli` utility to be present, but it
can now talk to remote nodes as well, including some lightweight nodes such
as [`spruned`][spruned]. This makes it possible to run a c-lightning node on
Raspberry Pis as well as other low-powered devices.
- The __gossip protocol__ has been updated to use a more lightweight bandwidth mechanism that
asks for specific information, rather than exchanging full network
Views as the previous release did. This is particular important for low-powered and mobile devices that
would otherwise spend a lot of bandwidth and energy downloading and
verifying information they already have.
- __API stability__: The c-lightning
JSON-RPC interface and supporting libraries have been redesigned in order to minimize
changes in future releases. This API stability should make it easy for other
projects to build on top of c-lightning because we will support this version of
the API for the foreseeable future, maintaining backward compatibility,
should we introduce any changes.
- __Wallet and sync__: c-lightning now includes a full-fledged wallet that
manages both on-chain and off-chain funds. There is no more raw
transaction handling! All funds are automatically tracked and returned to the
internal wallet as soon as possible, with no user interaction required. In
addition the blockchain tracking now maintains an internal view of the blockchain, ending long blockchain rescans.
- __TOR support__: c-lightning now supports connecting to nodes over the
TOR network, auto-registering as a hidden service, and accepting
incoming connections over TOR.
- The __payment logic__ has undergone a major overhaul to support automatic retries
for routing failures, randomization of route selection, and better feedback about
the current state of a payment.
- And as always: performance, performance, performance.
## Flexibility through Modularity
The c-lightning architecture is based on a number of independent communicating
processes, each with its own responsibilities. This allows better integration into
your infrastructure and better adaptation to your needs. Two
daemons that are global for all channels,`gossipd` and `hsmd`, are of particular note because of their modular design
`gossipd` manages a local view of the network and is tasked with finding a path
from the source of a payment to its destination. The default implementation
attempts to find a route with reasonable tradeoffs between fees, timeouts, and
stability. It also obfuscates the route by selecting randomly among a
number of candidate routes and tweaking the amounts and timeouts in order to
conceal the endpoints of a payment. The default implementation can easily be
switched out if you have particular routing requirements or want to
enforce a specific routing policy, such as always selecting the route with the lowest
timeouts or the lowest fees.
`hsmd` manages all operations that touch cryptographic materials and controls
the funds in the channel. It is the sole subsystem that has access to the node's
private key. This means that other subsystems do not hold any private
information and must communicate with the `hsmd` daemon to sign or decrypt
anything. Centralizing the cryptographic operations in this manner reduces the
surface that needs to be secured and opens up a number of interesting
applications. While the default `hsmd` implementation already provides good
security through process separation and the ability to further secure it via OS
level security, e.g., SELinux and AppArmor, it can be easily replaced with an implementation that talks to a physical HSM. Replacing the `hsmd`
implementation furthermore allows headless operation, e.g., running a
c-lightning node at home, with a paired mobile app managing the private keys
and initiating payments or creating invoices.
This separation of c-lightning functionality into multiple daemons is not only a big
improvement in flexibility, but also a robust improvement to node security, as it ensures that an attacker cannot directly
interface with anything that touches the private keys. Each subsystem
independently verifies the consistency of the internal state, disconnecting a
peer and killing its process if any inconsistency is detected. The multi-daemon
architecture also enables the use of Docker, SELinux and AppArmor to lock down
what information each daemon can access and what actions they can perform.
## What's Next?
Our work with c-lightning is far from done; we are constantly working on
[features][features] and [enhancements][enhancements], as well as improvements to
performance, stability and usability. Didn’t find your favorite feature? Have
some feedback that might be helpful? Why not file an [issue on
Github][gh-issue], drop us a line on the [mailing list][ml], or [contact us on
IRC][irc].
In parallel we are also contributing to the advancement of the Lightning specification
itself and are actively researching what the next iteration of the protocol could
look like through initiatives like our [eltoo][eltoo] proposal and upstream
Bitcoin proposals such as [`SIGHASH_NOINPUT`][sighash-noinput].
We'd like to thank the many contributors who have not only contributed code to
c-lightning, but also those who were #reckless enough to test and give feedback
about what works and what could be improved. And finally, we'd like to thank the
other Lightning Network teams, ACINQ and Lightning Labs, as well as all individual contributors
that pitched in to make the Lightning Network community such a pleasant, collaborative and open
environment!
[spruned]: https://github.com/gdassori/spruned
[clightning]: https://github.com/ElementsProject/lightning
[features]: https://github.com/ElementsProject/lightning/issues?q=is%3Aissue+is%3Aopen+label%3Afeature
[enhancements]: https://github.com/ElementsProject/lightning/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement
[irc]: irc://c-lightning@irc.freenode.net
[ml]: mailto:c-lightning@lists.ozlabs.org
[gh-issue]: https://github.com/ElementsProject/lightning/issues/new
[sighash-noinput]: https://github.com/bitcoin/bips/blob/master/bip-0118.mediawiki
[eltoo]: https://blockstream.com/2018/04/30/eltoo-next-lightning.html

4
doc/requirements.txt
View File

@ -1,4 +0,0 @@
mkdocs-exclude
mkdocs-material
mkdocs
Jinja2==3.1.0

0
doc/user/index.md
View File