From 75b29d9cda09a1198e1a01b0f98b6620c743c556 Mon Sep 17 00:00:00 2001 From: Ekaitz Zarraga Date: Mon, 25 Mar 2024 17:41:50 +0100 Subject: doc: document the project --- doc/neocities.texi | 279 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 277 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/neocities.texi b/doc/neocities.texi index 0d52ec0..d969793 100644 --- a/doc/neocities.texi +++ b/doc/neocities.texi @@ -47,14 +47,289 @@ This document describes Neocities version @value{VERSION}. @menu * Introduction:: Why Neocities? +* Installation:: How to install +* CLI:: Using the Command-Line Interface +* Guile API:: Using the Guile API +* Development:: Taking part and improving Guile-Neocities @end menu @c ********************************************************************* @node Introduction @chapter Introduction -INTRODUCTION HERE +This project is a CLI tool and a Guile API to interact with Neocities. -This documentation is a stub. +@node Installation +@chapter Installation + +With Guix you can just: + +@example +$ guix install -f guix.scm +@end example + +If you want to develop or install it in a different distribution you have to do +all by hand. + +@node Dependencies +@section Dependencies + +@subsection Run-time dependencies + +@itemize +@item +@code{guile-3} +@item +@code{guile-json-4} +@item +@code{guile-gcrypt} +@end itemize + +@subsection Development dependencies + +@itemize +@item +@code{autoconf} +@item +@code{automake} +@item +@code{pkg-config} +@item +@code{texinfo} +@item +@code{make} +@end itemize + +@node Building from source +@section Building from source + +Like other GNU projects you can build this using autotools and make. +Make sure you have the dependencies (both run-time and dev) installed. + +@example +$ autoreconf -vif +$ ./configure +$ make +@end example + +If you wish to install you can @command{make install}, too. + +@node CLI +@chapter CLI + +The command line interface has a set of commands to interact with Neocities. +Running @command{neocities --help} lists them all with the documentation: + +@example +$ neocities --help + +neocities + +USAGE: + + ENVIRONMENT VARIABLES: + Export them: + export NEOCITIES_USER=my_username + ... + Or use them in the command line call + NEOCITIES_USER=my_username ... neocities + + Authentication: + Your credentials + export NEOCITIES_USER=my_username + export NEOCITIES_PASS=my_password + Or your API key: + export NEOCITIES_KEY=my_key + + Target: + export NEOCITIES_HOST=my-neocities-host.org # defaults to neocities.org + + USAGE: + neocities @{--help|--version|@} + + Commands: + neocities list + neocities upload [...] + neocities delete [...] + neocities info + neocities key +@end example + +@node CLI Authentication +@section CLI Authentication + +Command-Line Interface makes use of environment variables to obtain the +credentials of the Neocities instance. + +You can use user/password authentication or the key. The command line example +in the previous section explains how to do that. + +@node Guile API +@chapter Guile API + +The very same functionality available from the command line is also available +using the Guile API. + +@node Initialization +@section Initialization + +There are two authentication methods available, user/pass and key, that can be +created using @code{make-neocities-auth-basic} and +@code{make-neocities-auth-api-key} respectively. + +@deffn {Procedure} make-neocities-auth-basic user pass + +Returns an authentication object based on username and password. + +@itemize +@item +@var{user}: String with the Neocities username +@item +@var{pass}: String with the Neocities password +@end itemize +@end deffn + +@deffn {Procedure} make-neocities-auth-api-key api-key + +Returns an authentication object based on an API-key. + +@itemize +@item +@var{api-key}: String with the API-Key obtained from Neocities +@end itemize +@end deffn + +Once the authentication method is created, the API access has to be created. +@code{make-neocities-api} procedure does that job. + +@deffn {Procedure} make-neocities-api host auth #:optional port + +Returns a Neocitites API object with the provided authentication. + +@itemize +@item +@var{host}: String with the hostname with the Neocities instance +@item +@var{auth}: Authentication object created with +@var{make-neocities-auth-api-key} or @var{make-neocities-auth-basic} +@item +@var{port}: Optional port number to connect to +@end itemize +@end deffn + +Once the API is created it can be used to call the API functions. + +@node Usage +@section Usage + +These are the available API calls to Neocities API. All of them use convert +their arguments to JSON and use the Neocities API. They return two +@code{values} as Guile's http interface would return using @code{(web +client)}'s @code{http-request}. The first is the @code{response}, but the +second, the @code{body}, converted from JSON to Scheme using @code{guile-json} +library if the request is successful. + +@deffn {Procedure} neocities-key api + +Obtain an API-Key from Neocities. + +@itemize +@item +@var{api}: API object created with @var{make-neocities-api}. +@end itemize +@end deffn + + +@deffn {Procedure} neocities-info api #:optional sitename + +Obtain info about the Neocities site. + +@itemize +@item +@var{api}: API object created with @var{make-neocities-api}. +@item +@var{sitename}: Optional argument. Site to get information from (string). +Defaults to the site of the authenticated user. +@end itemize +@end deffn + + +@deffn {Procedure} neocities-list api #:optional path + +Obtain list of files in Neocities site. + +@itemize +@item +@var{api}: API object created with @var{make-neocities-api}. +@item +@var{path}: Optional argument. Path to list (string). Defaults to the root +folder of the site (@code{/}). +@end itemize +@end deffn + + +@deffn {Procedure} neocities-upload api files + +Upload files to Neocities. + +@itemize +@item +@var{api}: API object created with @var{make-neocities-api}. +@item +@var{files}: List of pairs of paths. In the shape @code{((from . to) ...)} +@end itemize +@end deffn + + +@deffn {Procedure} neocities-delete api files + +Delete files from Neocities site. + +@itemize +@item +@var{api}: API object created with @var{make-neocities-api}. +@item +@var{files}: List of paths (strings) to delete. +@end itemize +@end deffn + + + +@node Helper functions +@section Helper functions + +Neocities returns important information inside of the responses of their API, +using the @code{result} field of their response, once the HTTP layer was +correctly processed. We also provide a function that checks that field to know +if the request was properly formulated. + +@deffn {Procedure} neocities-success? body + +Return @code{#t} if body represents a successful interaction and @code{#f} +otherwise. + +@itemize +@item +@var{body}: Body of the response, the second of the @code{values} returned by +any call to the Neocities API. +@end itemize +@end deffn + +@node Development +@chapter Development + +The project files are managed using @code{guile-hall}, which give us some +automation for all the autotools stuff. + +If you wish to test the code in your development environment, the tools should +provide you a @command{pre-inst-env} script that enables you to do that: + +@example +./pre-inst-env neocities --help +@end example + +On top of that, taking part in the project is similar to any GNU project. You +can send your patches to the maintainer (see the email in the commits) or in +the Github mirror. @bye -- cgit v1.2.3