Setup instructions confusing/unclear

[koeaw]

Is the command for creating a new project provided at the top of the "Installation" section in the README the right way around or do the arguments need swapping?

It currently reads:

$ poetry new foobar --name apis_ontology

which creates a directory with the name (of whatever is substituted for) foobar and sets tool.poetry.name to apis-ontology (note the changed format).

What I'm seeing in already existing apis-instance- repos suggests to me they ran the command:

$ poetry new apis_ontology --name apis-instance-PROJECT-NAME

where apis-instance-PROJECT-NAME is the same as the repo name.

If the latter is the correct format, what are the requirements for project name and/or repo name if any?

Can we choose whatever (foobar example), is there a naming recommendation (with regard to e.g. if we were to put this on PyPI, which would turn name into the official package name, or for reasons of consistency within ACDH-CH or whatever) or must the name follow a certain format (if only for internal use)? I.e. is apis-instance- a required prefix, does PROJECT-NAME need to match other config (container name used so far? subdomain name?), do project name and repo name need to be identical?

Happy to send a PR to fix/improve the setup instructions based on answers to this ticket.

[b1rger]

I don't think any of the existing apis-instance-* repositories used poetry for initializing the repository.

what are the requirements for project name and/or repo name if any?

there are none

Can we choose whatever (foobar example),

yes

is there a naming recommendation

there are three repositories using apis-instance- as prefix, so that might already count as best practice

must the name follow a certain format (if only for internal use)?

not that I'm aware of

I.e. is apis-instance- a required prefix, does PROJECT-NAME need to match other config (container name used so far? subdomain name?), do project name and repo name need to be identical?

no, no, no and no

(the instructions in the README.md were not written with a specific deployment setup in mind)

[koeaw]

In one of the last JFxs we briefly discussed the Install section in the README.

I volunteered to fix imprecise wording pointed out by @sennierer because I'd already started improving the instructions a bit anyway but forgot to assign this ticket to myself. (Still a WIP on my end, though I might open a draft PR.)

[b1rger]

The README has been updated a couple of times in the last few months. Is the issue still there? If so, can we make this an actionable item, by specifying what exactly is confusing/unclear?

[koeaw]

The README has been updated a couple of times in the last few months. Is the issue still there? If so, can we make this an actionable item, by specifying what exactly is confusing/unclear?

I'll check. I remember the original setup instructions didn't produce the expected results re: ... either file structure of the project or name given to the project in pyproject.toml.

[koeaw]

So, the thing that I found confusing is still part of the instructions, and a new bit of info adds to that.

I saw in my WIP branch that I created a separate Markdown file to move all the Poetry instructions to, I believe based on what @sennierer said in the JF I referenced above. IIRC the idea was to keep tool-specific instructions out of the main README.

I'll push what I currently have to a draft PR.

[koeaw]

Discussed with @sennierer yday:

Once #856 is merged, I'll transfer my more detailed instructions from #858 to docs/source/installation.rst (low priority TODO for me). We'll keep the current instructions for Poetry in the README but add a heads-up + link to the install docs for how to adjust them to system/env-specific needs.

[sennierer]

@sennierer to come up with a new suggestion, that simplifies the installation doc, but keeps docker/docker-compose

[b1rger]

@sennierer to come up with a new suggestion, that simplifies the installation doc, but keeps docker/docker-compose

This has been implemented in the meantime, so @koeaw does this issue still exist?