Merge with Create-Python-Project

[akaszynski]

We need to implement the following features from https://github.com/pyansys/create-python-project:

• Fully utilize pipx
• Add in fancy *gif (good idea @asbfall) and badges
• Create a common directory to share common files across multiple templates. This will avoid duplication of LICENSE, CONTRIBUTING, etc.
• Add in gRPC, REST, and docker templates. Use common files via a pre-hook
• Expand documentation with directions for adding additional templates.

Finally, we should discuss if we should be limiting these templates to just Python, or expand it into C#, C++, JavaScript, etc.

[jorgepiloto]

Pinging here @asbfall and @jgd10, since this issue is no longer blocked now we just released 0.1. Documentation includes directions on how to include custom templates for a given family, see: https://templates.pyansys.com/user_guide/templating.html

[asbfall]

Great @jorgepiloto. We will try to include at least one of our templates this week to validate the global approach.

[asbfall]

@jorgepiloto in your documentation https://templates.pyansys.com/user_guide/templating.html , it is stated: "Before adding a new template, it is important that you read the CONTRIBUTING section". I do not understand which CONTRIBUTING section you are referring to since there is even no ONTRIBUTING.md under this repository.

[asbfall]

@akaszynski @jorgepiloto You introduce the notion of a "family of templates". It was not clear to me the criteria that need to be considered to group a set of templates under the same family. For instance, by reading your documentation I initially thought that all ACE tailored templates will be grouped under the same family. Then by walking through the code I finally understand that the family there corresponds to the coding language for instance (e.g "python"). What I mean is that the convention/pattern (e.g domain-driven, audience-driven or technology-based, ...) should be documented so that any contributor clearly knows it in advance.

[jorgepiloto]

I do not understand which CONTRIBUTING section you are referring to since there is even no CONTRIBUTING.md under this repository.

You are right, @asbfall. We are working on ansys/pyansys-dev-guide#64 to have a generic "Contributing" section. Of course, projects can have a local "CONTRIBUTING" file too. Because you are experienced with the usual GitHub and development workflow, do not worry about this file for the moment.

You introduce the notion of a "family of templates". It was not clear to me the criteria that need to be considered to group a set of templates under the same family.

Thanks for your feedback on this. The main idea behind "family of templates" is to allow sharing resources across various templates which have some kind of relation. Our main goal is to avoid is duplication.

Most of the files in create-python-project/src/templates/share are already included in python/common/. In the end, they ship in the form of a Python library or have the usual src/, tests/ and doc/ layout. I think the best approach is to include the templates from create-python-projects in the templates/python directory using the ace prefix. Some suggestions:

• classic -> ace-classic
• rest-api -> ace-api or ace-rest-api
• package -> ace-pkg

What do you think about this approach, @asbfall?

[asbfall]

I do not understand which CONTRIBUTING section you are referring to since there is even no CONTRIBUTING.md under this repository.

You are right, @asbfall. We are working on pyansys/dev-guide#64 to have a generic "Contributing" section. Of course, projects can have a local "CONTRIBUTING" file too. Because you are experienced with the usual GitHub and development workflow, do not worry about this file for the moment.

You introduce the notion of a "family of templates". It was not clear to me the criteria that need to be considered to group a set of templates under the same family.

Thanks for your feedback on this. The main idea behind "family of templates" is to allow sharing resources across various templates which have some kind of relation. Our main goal is to avoid is duplication.

Most of the files in create-python-project/src/templates/share are already included in python/common/. In the end, they ship in the form of a Python library or have the usual src/, tests/ and doc/ layout. I think the best approach is to include the templates from create-python-projects in the templates/python directory using the ace prefix. Some suggestions:

• classic -> ace-classic
• rest-api -> ace-api or ace-rest-api
• package -> ace-pkg

What do you think about this approach, @asbfall?

@jorgepiloto I think it make sense. I'm wondering whether ace is the right prefix. I believe that those "ace" templates can be used by any developer that would like to build a project that is not product-related. However, I do not have better suggestion for the time being.

[jgd10]

I think there's a bigger issue with naming wrapped up in all of this.

Migrating acpp templates: I think the issue is that our templates were developed with ACE in mind, but were made for anyone. So, there's no reason why non-ACE developers couldn't use them. They don't contain code that is not for "developers"!

I think it means we should rearrange the groupings to be a bit more communicative. My goal going into this isn't to avoid code duplication so much as it is to produce a tool that provides a good user experience. So I'd propose more descriptive names. Instead of ace-rest-api it should probably be flask-rest-api maybe with a note in the documentation about who created it/who to contact about it. Rather than a family like ace, the big differentiation our templates have is that they use docker, so some sort of name indicating this like docker-based-templates might be appropriate.

The trouble with "ace" and "pyansys" is that they don't communicate much to the user about what they're getting. What's the difference between the pyansys and pyansys_advanced templates? At first glance it's very hard to know. As a user I wouldn't know what I was getting compared to say flask-rest-api or pyansys-library. What is it about pyansys_advanced that makes it more "advanced"? The names don't really tell us anything about what's in them. But perhaps they should.

This has become a bit long so I'd be happy to make a new ticket about this if it would be preferred.

[akaszynski]

The names don't really tell us anything about what's in them

I think the documentation has this covered: https://templates.pyansys.com/user_guide/usage.html#listing-available-templates

[jgd10]

The names don't really tell us anything about what's in them

I think the documentation has this covered: https://templates.pyansys.com/user_guide/usage.html#listing-available-templates

I think it helps but I don't think it's enough. I think we should be naming our templates such that people need to refer to the documentation as little as possible. That would produce the most streamlined UX possible. If we use vague and general terms like "ACE" and "pyansys" (they do not have rigorous definitions that are widely used) as our main descriptors, we will have to take up documentation space explaining what those mean (and if we don't people will wonder), when people really just need to know "this is a flask-based rest-api template" or "this is a template for a python package". It might mean slightly longer template names but I think it would be worth it.

If we are building templates specifically for "ACE" or "pyansys", then I think they should have names that represent their purpose rather than who is going to use them and if there is a significant, fundamental, discrepancy between the templates that we develop for ACE and you develop for pyansys, then we should identify what this is and potentially include descriptors for THAT in the names. You might say "well we develop our templates for people who want to create new pyansys products" and sure that's fine, but then you have a pyansys template and a pyansys_advanced template and a pybasic template, so if a user comes along who wants to create a new pyansys product, which are they going to go for? What do "basic", "advanced", and no epithet mean here? The names (and the descriptions) are not clear on this. We have the same problem with the classic template. It's very similar to the package template and so... why does it exist? What does it do differently? From a user perspective you have no idea!

I think it only matters to us whether it's pyansys or ace, but I doubt our users are bothered about that. They will just want the right tool for the right job and anything we put in their way of working out what that tool is, is a hindrance.

So some suggestions:

• pybasic
  • pyansys-skeleton - the name would imply there are just the barebones present, and there's a lot you will have to fill in yourself
• pyansys_advanced
  • pyansys-developer-version - indicates a greater degree of complexity and that it expects it will be for more sophisticated/experienced users
• package
  • library-skeleton - This is a python library, but doesn't contain any bells and whistles like docker, or other things.
• classic
  • script - This template could be just for someone creating a python script rather than a package and so can be labelled as such, to reduce confusion with package (or whatever we end up calling it).