New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Task initArc42** should use sensible default for docDir or should make it mandatory #137

Open
thokuest opened this Issue Jan 24, 2018 · 11 comments

Comments

Projects
None yet
4 participants
@thokuest

thokuest commented Jan 24, 2018

Expected behavior and actual behavior.

When I execute the initArc42EN task without providing a docDir (as in -PdocDir=<your directory>), the downloaded zip file is extracted into the project's root directory. As a user, I'd expect that docDir is either defaulted or that the build fails if the mandatory parameter are not given.

Steps to reproduce the problem.

./gradlew -b init.gradle initArc42EN

Specifications like the version of the project, operating system, or hardware.

master at commit 6f5dc7d.

@rdmueller

This comment has been minimized.

Collaborator

rdmueller commented Jan 24, 2018

maybe the build prompt for the dir?

@jakubjab jakubjab self-assigned this Jan 24, 2018

@jakubjab

This comment has been minimized.

Member

jakubjab commented Jan 24, 2018

I would fix it by making it mandatory, I don't think a default value makes sense (would be like expecting gcc to compile some default file).

@rdmueller

This comment has been minimized.

Collaborator

rdmueller commented Jan 24, 2018

so, first parameter has to start with . or / ?
and in case of windows [a-z]:

@jakubjab

This comment has been minimized.

Member

jakubjab commented Jan 24, 2018

I thought of just making it required by using a different property, newDocDir in init.gradle, which is not specified in gradle.properties. I'll make a PR in a minute.

If I have some time later, I could use the "frontend" doctoolchain script to make the initialization task. That would be nicer I guess.

jakubjab added a commit to jakubjab/docToolchain that referenced this issue Jan 24, 2018

rdmueller added a commit that referenced this issue Jan 24, 2018

Merge pull request #138 from jakubjab/master
Fix for #137 making target directory mandatory for initialization
@jakubjab

This comment has been minimized.

Member

jakubjab commented Feb 27, 2018

I'm working on refactoring the frontend script, and here is my proposal for it's interface:

Overview: AsciiDoc Toolchain for Software Architecture Documentation

Usage: doctoolchain [options]

Options:
  -d <docDir>         Absolute or relative directory with the documentation source.
  -l                  Lists available tasks.
  -t <task>           Task to do.
  -i <template>       Initialize docDir with an official arc42 template.
                      The name of the template should match a name of a file available from
                      https://github.com/arc42/arc42-template/tree/master/dist
                      without the extension, for example:
                        arc42-template-DE-plain-asciidoc
                        arc42-template-EN-withhelp-asciidoc
  -e                  Initialize docDir having an existing contents for use with doctoolchain.
  -h                  Print help and exit.

Key tasks:
  generatePDF
  generateHTML
  publishHTMLToConfluence [-c <configuration>]

Examples:
  Generate PDF from documents in myDocs directory:
    doctoolchain -d myDocs -t generatePDF

  Generate HTML from documents in current directory:
    doctoolchain generateHTML

  Publish generated HTML to Confluence:
    doctoolchain publishHTMLToConfluence -c ConfluenceConfig.groovy

Any comments are welcome.

@rdmueller

This comment has been minimized.

Collaborator

rdmueller commented Feb 27, 2018

@jakubjab that's great!

Here is my feedback:

-e could be also implemented through -i without a template name or existing as name

-i I would like to add more templates. For instance for user manuals. So, if we create some kind of config for different repositories, that would be great!

Examples : I would add as first example the init task.

-l, -t: I liked the old mechanic, that all remaining parameters are passed through to gradle. Maybe we could combine this?

-d: it would be cool if the script would ask for the <docDir> if missing :-)

@jakubjab

This comment has been minimized.

Member

jakubjab commented Feb 28, 2018

My comments:

-e could be also implemented through -i without a template name or existing as name

I would vote for -i without a template name, I don't like making existing a magic keyword.

-i I would like to add more templates.

Do we have more templates somewhere on the web as examples?

-l, -t

I would like to separate the interface from the implementation, so that it's possible to use this tool without knowing about gradle. But for those knowing gradle, I would give -X option to pass other options to gradle directly.

-d

It's missing in the description, but I would take the current directory if it's missing. So the user can just enter the directory with their source code and type doctoolchain (we could have default task configurable as well).

@bodewig

This comment has been minimized.

Contributor

bodewig commented Feb 28, 2018

I've been mostly absent, sorry about that.

I second "I don't like making existing a magic keyword", but am not sure we'd be overloading -i too much anyway, in particular if we add more templates.

TBH I'm not sure what the original -e is supposed to do (I must admit I've only ever used the publish-to-confluence part so far), does it mean "use what is already inside docdir"? If so it wouldn't do any initialization at all and it could as well mean "omit -i completely?

@jakubjab

This comment has been minimized.

Member

jakubjab commented Feb 28, 2018

-e was supposed to be used if you already have some asciidoc documents, and don't want to download new template, but just need to start using doctoolchain with them. The same could be achieved with -i without any template. If is just copying configuration files to the target directory.

Honestly, I was also thinking to keep those use cases separate: initializing the workspace and generating documentation. You are usually initializing the workspace once per project, and this doesn't happen every day (in my world at least). I don't mind to do it manually - getting the template for the documentation is the least of a problem when you start a new project. Quite often there is company-specific template or just existing example of documentation that needs to be copied.

I understand that fetching the template might be useful in promoting arc42, but I wouldn't like to spend too much effort and gold-plating on this part, I would rather make the main part - generating documents - more stable.

To make the interface more future proof, we could make -i option to take URL as argument, like https://github.com/arc42/arc42-template/blob/master/dist/arc42-template-EN-plain-asciidoc.zip, then the first-time users are freed from the burden of finding, downloading and unzipping it, and they can get something building in a few simple steps:

cd myDocDir
doctoolchain -i https://github.com/arc42/arc42-template/blob/master/dist/arc42-template-EN-plain-asciidoc.zip
doctoolchain generateHTML

Then if we have some company-specific or open source repository of templates, quite likely they can be referenced with URL and then doctoolchain works out of the box.

@rdmueller

This comment has been minimized.

Collaborator

rdmueller commented Feb 28, 2018

as you say: you do not often initialize a repository and that's why I think it should be easy and intuitive.
Do you know lazybones? https://github.com/pledbrook/lazybones

It is a template tool for project templates and it solves this problem very well:

  • you can specify the template via url
  • there is a curated repository in which template definitions reside
  • you can add to this list through a local config

Furthermore, you can list all templates

I don't think that we should implement all these features at once, but I guess we should keep this option open. Maybe just as another gradle task.

Currently, we only have arc42 available, but I can already think of additional templates for requirements (http://www.volere.co.uk/template.htm), user manuals or or plugin description.

another question for me is if we should implement all of this as gradle task (started through the shell script) or as plain shell script?

@jakubjab

This comment has been minimized.

Member

jakubjab commented Feb 28, 2018

Sure, we could have it, but even lazybones is a separate project, not coupled with e.g. gradle. When starting to work on C++ project, I don't expect gcc to give me option to generate hello world program, but in XCode or other IDEs it's quite common. That's what I mean with separating concerns and use cases.

If we separate interface (shell script) from the implementation, we could easily make implementation of simple features directly in shell and complex ones in gradle. But gradle seems cross-platform, and shell scripts are not.

How about this:

Overview: AsciiDoc Toolchain for Software Architecture Documentation

Usage: doctoolchain [options] [<task>]

Options:
  -d <docDir>         Absolute or relative directory with the documentation source.
                      If the option is missing, the current directory is used.
  -l                  Lists available tasks and templates.
  -t <template>       Template to be used when initializing docDir directory.
  -c <confluence>     Confluence configuration file to be used when publishing.
  -h                  Print help and exit.

Key tasks:
  init
    Invoked with -t option, initializes docDir with a given template.
    Invoked without -t option, initializes docDir having an existing
    contents for use with doctoolchain.

  generatePDF, generateHTML
    Generates PDF or HTML documents from the asciidoc source.

  publishHTMLToConfluence [-c <configuration>]
    Publishes generated HTML document to Confluence.
    Invoked with -c option, uses configuration from the given file.
    Invoked without -c option, uses configuration from the default ConfluenceConfig.groovy file.

Examples:
  Initialize empty directory with an English arc42 template:
    > cd myDocs
    > doctoolchain -t arc42EN init

  Initialize existing directory with some asciidoc documents to be used with doctoolchain:
    > cd myOldDocs
    > doctoolchain init

  Generate PDF from documents in myDocs directory:
    > doctoolchain -d myDocs generatePDF

  Generate HTML from documents in current directory:
    > doctoolchain generateHTML

  Publish generated HTML to Confluence:
    > doctoolchain publishHTMLToConfluence -c ConfluenceConfig.groovy

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment