Closed ralphptorres closed 10 months ago
Wow this looks awesome, thank you for taking the time to create this! I will take some time to properly read it and maybe add some new bits here and there.
There will be a bit more maintanance work for me to keep both documentations in sync, but I think thats worth it.
A question that I had was how the distribution of the docs should work, at the moment I am building the binary from source on the users machine at install time, which is why it is important that there are no build time dependencies (those usually stop working sooner or later on someones machine). The way I did it with the website is to have a branch where the source of the site is and then I compile it locally and push the compiled filed to the gh-pages branch. Maybe we could do something similar here as well, i.e. the documentation is stored on the documentation
branch where I build it using the scdoc
dependency and then copy a compiled version of the docs to the main branch before each release where it is then distributed at install time. What do you think?
Thanks! No worries, please take your time. :)
Conveniently, the syntax used by scdoc closely resembles markdown (except the tables for practical reasons). So once we initially establish an agreement between the contents of the two documentations, atomic updates will be easy to carry out.
Re: compilation, scdoc is very minimal so build time should be negligible. But I am okay with your suggestion to compile the source doc only when it gets updated and just ship the compiled doc. I saw yabai keeps both its source doc (uses asciidoc) and compiled doc together in its master branch. However it compiles the source doc during the build process. In contrast, alacritty keeps only its source doc (also uses scdoc) but bundles the compiled equivalent in the binaries upon release (but again brew's alacritty is a cask and it still doesn't have the option to build itself from source so this is a moot).
I went through all of it and I really like it! Can you make sure that I did not mess something up in the process before I merge this?
Lgtm! Also, did very slight modifications to fix the things I missed in the initial commit.
Thanks again! It will be included in the next version, which will be released some time next week.
No problem, thanks as well.
The local documentation is included in v2.18.0, I have decided to just host the tar of the build docs on the website such that I can simply curl it during installation via
curl "https://felixkratz.github.io/SketchyBar/documentation.tar.gz" -o "./documentation.tar.gz"
and install them.
This commit adds locally available documentation to the project via a set of man pages. The contents were derived from the docs dir of the base repo's documentation branch. This dir contains the very same contents used by the online documentation.
The contents were minimally tweaked but still very closely followed the original. The examples were lifted mostly from the project's sample config file and the discussion pages linked in the original.
The documentation follows the structure in the original and is split into 10 files. Except for the following changes, the structure is essentially the same:
Finally, this commit will add
scdoc
(see https://sr.ht/~sircmpwn/scdoc) as a dependency. This utility may be used to build roff style man pages from the scd files during build times.