diff --git a/.gitignore b/.gitignore index 19673dd..a0d5128 100644 --- a/.gitignore +++ b/.gitignore @@ -7,10 +7,12 @@ !*.* !*/ !ChangeLog +!Makefile # Any path *.swp *~ +_build/ build/ nimcache/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0f91f8 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,23 @@ +# SPDX-FileCopyrightText: 2022 Anna +# 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) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..2889bd8 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,36 @@ +# SPDX-FileCopyrightText: 2022 Anna +# 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 diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..15b85f0 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,46 @@ +.. SPDX-FileCopyrightText: 2022 Anna +.. +.. 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/ diff --git a/docs/getting-started.rst b/docs/getting-started.rst new file mode 100644 index 0000000..6bcb304 --- /dev/null +++ b/docs/getting-started.rst @@ -0,0 +1,71 @@ +.. SPDX-FileCopyrightText: 2022 Anna +.. +.. 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`. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..65d2118 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,31 @@ +.. SPDX-FileCopyrightText: 2022 Anna +.. +.. 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: + +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 diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..cfe49e3 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,56 @@ +.. SPDX-FileCopyrightText: 2022 Anna +.. +.. 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 diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..5617e85 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,38 @@ +# SPDX-FileCopyrightText: 2022 Anna +# 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 diff --git a/docs/toc.rst b/docs/toc.rst new file mode 100644 index 0000000..d948060 --- /dev/null +++ b/docs/toc.rst @@ -0,0 +1,16 @@ +Table of Contents +================= + +.. toctree:: + + index + installation + getting-started + contributing + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search`