docs/*: add Sphinx docs
This commit is contained in:
Anna “CyberTailor”
parent
089cf83ef5
commit
cd484a637c
GPG Key ID:
E7B76EDC50864BB1
|
|
@ -7,10 +7,12 @@
|
|||
!*.*
|
||||
!*/
|
||||
!ChangeLog
|
||||
!Makefile
|
||||
|
||||
# Any path
|
||||
*.swp
|
||||
*~
|
||||
_build/
|
||||
build/
|
||||
nimcache/
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,23 @@
|
|||
# SPDX-FileCopyrightText: 2022 Anna <cyber@sysrq.in>
|
||||
# SPDX-License-Identifier: CC0-1.0
|
||||
#
|
||||
# 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)
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
# SPDX-FileCopyrightText: 2022 Anna <cyber@sysrq.in>
|
||||
# SPDX-License-Identifier: CC0-1.0
|
||||
#
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# For the full list of built-in configuration values, see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
||||
|
||||
project = 'nimbus'
|
||||
copyright = '2022, Anna (cybertailor) Vyalkova & Nimble Authors'
|
||||
author = 'Anna (cybertailor) Vyalkova & Nimble Authors'
|
||||
release = '1.0.0'
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
|
||||
|
||||
extensions = [
|
||||
'notfound.extension',
|
||||
'sphinx-prompt'
|
||||
]
|
||||
|
||||
root_doc = 'toc'
|
||||
templates_path = ['_templates']
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
manpages_url = 'https://docs.sysrq.in/{path}'
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
|
||||
|
||||
html_theme = 'insipid'
|
||||
html_static_path = ['_static']
|
||||
html_title = f'{project} {release}'
|
||||
html_show_sourcelink = False
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
.. SPDX-FileCopyrightText: 2022 Anna <cyber@sysrq.in>
|
||||
..
|
||||
.. SPDX-License-Identifier: BSD-3-Clause
|
||||
|
||||
Contributing
|
||||
============
|
||||
|
||||
Any form of contribution is welcome!
|
||||
|
||||
Workflow
|
||||
--------
|
||||
|
||||
First, get the source code:
|
||||
|
||||
.. prompt:: bash
|
||||
|
||||
git clone https://git.sysrq.in/nimbus
|
||||
|
||||
Make some changes and run the tests:
|
||||
|
||||
.. prompt:: bash
|
||||
|
||||
testament all
|
||||
|
||||
Commit the changes. Your commit message should conform to the following
|
||||
standard::
|
||||
|
||||
file/changed: concice and complete statement of the purpose
|
||||
|
||||
This is the body of the commit message. The line above is the
|
||||
summary. The summary should be no more than 72 chars long. The
|
||||
body can be more freely formatted, but make it look nice. Make
|
||||
sure to reference any bug reports and other contributors. Make
|
||||
sure the correct authorship appears.
|
||||
|
||||
Use `git rebase`_ if needed to make commit history look good.
|
||||
|
||||
.. _git rebase: https://git-rebase.io/
|
||||
|
||||
Finally, send a patch to the developer using `git send-email`_:
|
||||
|
||||
.. prompt:: bash
|
||||
|
||||
git send-email --to=cyber@sysrq.in origin/master
|
||||
|
||||
.. _git send-email: https://git-send-email.io/
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
.. SPDX-FileCopyrightText: 2022 Anna <cyber@sysrq.in>
|
||||
..
|
||||
.. SPDX-License-Identifier: BSD-3-Clause
|
||||
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
.. note::
|
||||
Make sure the project you want to build uses NimScript package file format.
|
||||
INI format is deprecated and not supported by nimbus.
|
||||
|
||||
Setup
|
||||
-----
|
||||
|
||||
.. prompt:: bash
|
||||
|
||||
cd my-nim-project
|
||||
mkdir build && cd build
|
||||
nimbus ..
|
||||
|
||||
This command will create a :file:`ninja.build` file in the build directory.
|
||||
|
||||
.. seealso:: :manpage:`nimbus.1` manual page
|
||||
|
||||
All the following commands need to be called from the build directory.
|
||||
|
||||
Compile
|
||||
-------
|
||||
|
||||
.. prompt:: bash
|
||||
|
||||
ninja
|
||||
|
||||
This command will build all project binaries, if any. If there are multiple, you
|
||||
can choose which to build:
|
||||
|
||||
.. prompt:: bash
|
||||
|
||||
ninja myprog
|
||||
|
||||
Run tasks
|
||||
---------
|
||||
|
||||
A ninja target is created for every Nimble task. You can run them on request:
|
||||
|
||||
.. prompt:: bash
|
||||
|
||||
ninja scss
|
||||
|
||||
Run tests
|
||||
---------
|
||||
|
||||
.. prompt:: bash
|
||||
|
||||
ninja test
|
||||
|
||||
This command will run "test" task (if defined). Otherwise, it will compile and
|
||||
run all Nim files in the file:`tests` directory beginning with "t" in their
|
||||
filename.
|
||||
|
||||
This behavior is compatible with Nimble.
|
||||
|
||||
Install
|
||||
-------
|
||||
|
||||
.. prompt:: bash
|
||||
|
||||
DESTDIR=/tmp/prefix ninja install
|
||||
|
||||
This command will install the package (both sources and binaries) into
|
||||
:file:`/tmp/prefix`.
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
.. SPDX-FileCopyrightText: 2022 Anna <cyber@sysrq.in>
|
||||
..
|
||||
.. SPDX-License-Identifier: BSD-3-Clause
|
||||
|
||||
nimbus
|
||||
======
|
||||
|
||||
nimbus is a build system for `Nim`_. It is compatible with the `Nimble`_ package
|
||||
format, so you can use it to build and install packages from the `Nimble
|
||||
Directory`_ and other sources.
|
||||
|
||||
.. _Nim: https://nim-lang.org/
|
||||
.. _Nimble: https://nimble.directory/
|
||||
.. _Nimble Directory: <https://nimble.directory/>
|
||||
|
||||
If you want to learn about how to use nimbus, check out the following resources:
|
||||
|
||||
* :doc:`installation`
|
||||
* :doc:`getting-started`
|
||||
|
||||
If you need help, or want to talk to the developers, use our chat rooms:
|
||||
|
||||
* IRC: `#nimbus`_ at ``irc.oftc.net``
|
||||
* Matrix: `#nimbus:matrix.org`_
|
||||
|
||||
.. _#nimbus: https://kiwiirc.com/nextclient/#ircs://irc.oftc.net:+6697/nimbus
|
||||
.. _#nimbus\:matrix.org: https://matrix.to/#/#nimbus:matrix.org
|
||||
|
||||
If you find any bugs, please report them on `Bugzilla`_.
|
||||
|
||||
.. _Bugzilla: https://bugs.sysrq.in/enter_bug.cgi?product=Software&component=nimbus
|
||||
|
|
@ -0,0 +1,56 @@
|
|||
.. SPDX-FileCopyrightText: 2022 Anna <cyber@sysrq.in>
|
||||
..
|
||||
.. SPDX-License-Identifier: BSD-3-Clause
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
The only build dependency is the Nim compiler. However, depfile support is only
|
||||
available in the `patchset`_. To apply it in Gentoo, build ``dev-lang/nim`` with
|
||||
``experimental`` USE flag.
|
||||
|
||||
.. _patchset: https://git.sysrq.in/nim-patches/
|
||||
|
||||
Runtime dependencies are Nim (needed to run scripts) and either `ninja`_ or
|
||||
`samu`_.
|
||||
|
||||
.. _ninja: https://ninja-build.org/
|
||||
.. _samu: https://github.com/michaelforney/samurai
|
||||
|
||||
Gentoo
|
||||
------
|
||||
|
||||
nimbus is packaged for Gentoo in the GURU ebuild repository.
|
||||
|
||||
.. prompt:: bash #
|
||||
|
||||
eselect repository enable guru
|
||||
emaint sync -r guru
|
||||
emerge dev-nim/nimbus
|
||||
|
||||
Other distributions
|
||||
-------------------
|
||||
|
||||
.. image:: https://repology.org/badge/vertical-allrepos/nim:nimbus.svg
|
||||
:alt: Packaging status on Repology
|
||||
:target: https://repology.org/project/nim:nimbus/versions
|
||||
|
||||
Manual installation
|
||||
-------------------
|
||||
|
||||
Using Nim:
|
||||
|
||||
.. prompt:: bash
|
||||
|
||||
git clone https://git.sysrq.in/nimbus
|
||||
cd nimbus
|
||||
nim c src/nimbus
|
||||
|
||||
Using Nimble:
|
||||
|
||||
.. prompt:: bash
|
||||
|
||||
nimble install https://git.sysrq.in/nimbus
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
# SPDX-FileCopyrightText: 2022 Anna <cyber@sysrq.in>
|
||||
# SPDX-License-Identifier: CC0-1.0
|
||||
|
||||
@ECHO OFF
|
||||
|
||||
pushd %~dp0
|
||||
|
||||
REM Command file for Sphinx documentation
|
||||
|
||||
if "%SPHINXBUILD%" == "" (
|
||||
set SPHINXBUILD=sphinx-build
|
||||
)
|
||||
set SOURCEDIR=.
|
||||
set BUILDDIR=_build
|
||||
|
||||
%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
|
||||
)
|
||||
|
||||
if "%1" == "" goto help
|
||||
|
||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
goto end
|
||||
|
||||
:help
|
||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
|
||||
:end
|
||||
popd
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
Table of Contents
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
|
||||
index
|
||||
installation
|
||||
getting-started
|
||||
contributing
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
Loading…
Reference in New Issue