ArchUnit needs better (user) documentation about archunit HOT 14 CLOSED

Puh, for a moment I thought you meant 'architecture documentation' (about which I've already had a bad conscience for a while 😉)

But yes, you're right, the user documentation isn't very good, and the README.md is already getting to its limits. I've kind of procrastinated this for a while, but I guess, I'll take your push and start working on this issue.

To be honest, I have hardly any experience with Jekyll and Github Pages, but I've looked into it, and took your advice, to steal some basics (like using the "Minimal Mistakes" theme) from arc42.org. I've pushed a basic frame together with a docker-compose config (thanks for the tip, when I quickly tried Jekyll a while ago, I was kind of shocked about all the stuff I had to install). See https://github.com/TNG/ArchUnit/tree/gh-pages. I'll try to migrate things from the README.md and fill in more content over the next weeks. Once it's ready, I'll forward www.archunit.org to it.

I'd be grateful for any advice about my setup (as I said, new area for me, and the Jekyll config is kind of overwhelming at the beginning).

Also, if you have any pointers about things I should include in the docs, I'd be happy to hear them, as well. For me it's sometimes hard to imagine where the real problems in getting started are. I've tried to include everything to get going in the README.md, but I've realized, that I forgot many things (like how to configure importing main vs test, etc.)

But I should also start to write a real manual in Asciidoc, I think.

Anyway, thanks a lot for bringing this up and offering support!! Highly appreciated 😃

from archunit.

another (maybe even better) source for re-using doc is the Venom-Story...

Did the docker-stuff (from arc42.org-site) work for you?

from archunit.

btw, for github-pages, you don't need an orphaned branch any longer... you can configure github to publish your pages from any subdirectory...

from archunit.

Yes I saw, that I could put it all into docs for example, but I was wondering, if it's better to keep stuff bound to a special tool like Jekyll on a separate branch and only keep the Asciidoc for an user manual in master:/docs. But probably it would be an easier setup, if I just put it together on master, and configure Jekyll / Gradle, to handle the adocs correctly.

For Docker, I found that there meanwhile already is a complete jekyll/jekyll image, so it was pretty easy, I just added the Docker Compose file from https://github.com/jekyll/docker. I still have to do some tests, to see if following the README.md really leads to a working website from a clean checkout.

from archunit.

from archunit.

too bad I've no experience with asciidoc + jekyll... there are options, though:

https://rgra.github.io/, which is based upon https://github.com/asciidoctor/jekyll-asciidoc

from archunit.

aarg: the standard jekyll/docker setup currently builds with:

Creating archunit_site_1 ...
Creating archunit_site_1 ... done
Attaching to archunit_site_1
site_1  | Bundler can't satisfy your Gemfile's dependencies.
site_1  | Install missing gems with `bundle install`.

and then starts installing... (into the running container, thus potentially loosing the installed gems)

I'd prefer to install this into the docker container just once...

the startup time of the standard jekyll is (on my Mac) approx 30secs,
startup of my (customized) jekyll 3-5 secs...

from archunit.

Yes, you're right, would save a lot of building time, to preinstall the gems. So my next steps will be to
a) integrate gh-pages into master:/docs
b) prepare a customized docker image that has the gems installed already

from archunit.

if you do step a), I can care about b) afterwards...

(another advantage: you can manage multiple jekyll sites on your machine, with different themes and gem configurations...)

from archunit.

Okay, the site now resides in master:/docs
I created a custom docker image archunit/jekyll, that has the dependencies preinstalled, I'm sure it would be possible to shave off a couple MBs by not extending the official one (or maybe using jekyll/minimal)...
If you do a clean checkout and docker-compose run --rm --service-ports site, does the local server work without pulling any additional dependencies?

from archunit.

FYI @gernotstarke : We tried the approach with jekyll-asciidoc and it worked really neat... locally... ☹️
Seems like Github Pages doesn't whitelist the Gem: https://yermilov.github.io/blog/2017/02/20/using-jekyll-asciidoctor-and-github-pages-for-static-site-creation/
So I guess for now we'll create the HTML and check it in, hoping that in the future this will be a more painless process...

from archunit.

I created a PR to show a (draft) combination of diagram and source:

from archunit.

I've regenerated the html, looks good 😃
Only that now you need to have 'dot' installed, or the gradle asciidoctor will fail, but I don't think that's a problem, since only a very limited number of people ever generate the user guide 😉
I think this will be a valuable illustration of intention <-> code mapping...

from archunit.

well done, Peter!

from archunit.