search

emmo-repo / EMMOntoPy

Library for representing and working with ontologies in Python
https://emmo-repo.github.io/EMMOntoPy
BSD 3-Clause "New" or "Revised" License
40 stars 9 forks source link

Clean up demo, examples and docs #193

Closed CasperWA closed 3 years ago

CasperWA commented 3 years ago

Move demo and examples under docs and clean up the structure surrounding it.

CasperWA commented 3 years ago

@francescalb @jesper-friis So what do you think? Should we move the demo and examples folders into the docs folder and make it solely a part of the documentation? Or do you think it might still be nice to have one or both of these folder in the root and separate from the documentation for users to play around with if they git clone the repository?

francescalb commented 3 years ago

I see your point of separating them out into the documentation only. I often look for examples in the repo itself, but that is usually in not very mature packages. I am not sure what we should do here as I like cloning myself, but I am not sure if that is the best way to work.

From: Casper Welzel Andersen @.> Sent: onsdag 22. september 2021 11.53 To: emmo-repo/EMMO-python @.> Cc: Francesca Lønstad Bleken @.>; Mention @.> Subject: Re: [emmo-repo/EMMO-python] Clean up demo, examples and docs (#193)

@francescalbhttps://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Ffrancescalb&data=04%7C01%7Cfrancesca.l.bleken%40sintef.no%7C497df2633e194db7c90708d97daeb3ed%7Ce1f00f39604145b0b309e0210d8b32af%7C1%7C0%7C637679011558201895%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=Rq2%2F0jUms8uLDvN%2F4YQvnQtgGcnjr4NfAmWzU%2FUig2g%3D&reserved=0 @jesper-friishttps://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fjesper-friis&data=04%7C01%7Cfrancesca.l.bleken%40sintef.no%7C497df2633e194db7c90708d97daeb3ed%7Ce1f00f39604145b0b309e0210d8b32af%7C1%7C0%7C637679011558211848%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=1WCW1iGZlOdXxukmDxnb7jgxzF0s2aBOgdRW6wUYLek%3D&reserved=0 So what do you think? Should we move the demo and examples folders into the docs folder and make it solely a part of the documentation? Or do you think it might still be nice to have one or both of these folder in the root and separate from the documentation for users to play around with if they git clone the repository?

- You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Femmo-repo%2FEMMO-python%2Fissues%2F193%23issuecomment-924768702&data=04%7C01%7Cfrancesca.l.bleken%40sintef.no%7C497df2633e194db7c90708d97daeb3ed%7Ce1f00f39604145b0b309e0210d8b32af%7C1%7C0%7C637679011558211848%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=bn0bnlEKlbp3rsDbnh8DMkn9aVZooQZ8x4nBzXkPsyE%3D&reserved=0, or unsubscribehttps://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FALPGAD6R7OOIZWW32WAGF5TUDGRODANCNFSM5CLMUICQ&data=04%7C01%7Cfrancesca.l.bleken%40sintef.no%7C497df2633e194db7c90708d97daeb3ed%7Ce1f00f39604145b0b309e0210d8b32af%7C1%7C0%7C637679011558221820%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=YKmKfRTC1sN0GcwCNrD%2FTYcCyuzpcJ7FRl9oltbvv0U%3D&reserved=0. Triage notifications on the go with GitHub Mobile for iOShttps://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fapps.apple.com%2Fapp%2Fapple-store%2Fid1477376905%3Fct%3Dnotification-email%26mt%3D8%26pt%3D524675&data=04%7C01%7Cfrancesca.l.bleken%40sintef.no%7C497df2633e194db7c90708d97daeb3ed%7Ce1f00f39604145b0b309e0210d8b32af%7C1%7C0%7C637679011558221820%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=gweuGM%2Fbd74%2FRj8y8o0I5nC0gFENp58XSctXXu5A9tw%3D&reserved=0 or Androidhttps://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fplay.google.com%2Fstore%2Fapps%2Fdetails%3Fid%3Dcom.github.android%26referrer%3Dutm_campaign%253Dnotification-email%2526utm_medium%253Demail%2526utm_source%253Dgithub&data=04%7C01%7Cfrancesca.l.bleken%40sintef.no%7C497df2633e194db7c90708d97daeb3ed%7Ce1f00f39604145b0b309e0210d8b32af%7C1%7C0%7C637679011558221820%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=lxRwQEsbpwMKOksRebe%2BL8dmWRx%2Fyvt9UFQFFPvOeP8%3D&reserved=0.

CasperWA commented 3 years ago

I see your point of separating them out into the documentation only. I often look for examples in the repo itself, but that is usually in not very mature packages. I am not sure what we should do here as I like cloning myself, but I am not sure if that is the best way to work.

We can also do what I've set up in the current draft PR #222, namely to symlink the demo and examples folders in the docs folder in order to include them in the documentation, but still keep them in the root folder.

However, I am unsure it this is what we want. If you use the workflow of "git clone -> check repo examples" in general, then it would be more helpful to have a root examples folder. However, I'd argue that perhaps most of these things should either be learned through the documentation or available Jupyter Notebooks, e.g., where one could test out and learn how to use the package and the tools? The latter could be done with mybinder or a page of simple setup instructions in the documentation for how to install and start a Jupyter server in the correct "demo/examples" folder location.

In this way the demonstrations and examples are consciously labeled as "documentation".

Also, what is the difference between demonstrations (demo) and examples here? Isn't it essentially the same thing? Or is "demo" more of an example to use multiple tools at once, where examples are tool-specific?

francescalb commented 3 years ago

I agree with your points. I just have to work differently 😊 And it nice to put all documentation together. I think demos and examples can be joined. Demos are older, but in principle they can be put together I think.

From: Casper Welzel Andersen @.> Sent: onsdag 22. september 2021 13.28 To: emmo-repo/EMMO-python @.> Cc: Francesca Lønstad Bleken @.>; Mention @.> Subject: Re: [emmo-repo/EMMO-python] Clean up demo, examples and docs (#193)

I see your point of separating them out into the documentation only. I often look for examples in the repo itself, but that is usually in not very mature packages. I am not sure what we should do here as I like cloning myself, but I am not sure if that is the best way to work.

We can also do what I've set up in the current draft PR #222https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Femmo-repo%2FEMMO-python%2Fpull%2F222&data=04%7C01%7Cfrancesca.l.bleken%40sintef.no%7C83f5ca90d4744d171cae08d97dbc0485%7Ce1f00f39604145b0b309e0210d8b32af%7C1%7C0%7C637679068749724348%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=K1EDt9O9JlMHf9G9%2BLTPYxKNJecpdksreP9Vj14utZ4%3D&reserved=0, namely to symlink the demo and examples folders in the docs folder in order to include them in the documentation, but still keep them in the root folder.

However, I am unsure it this is what we want. If you use the workflow of "git clone -> check repo examples" in general, then it would be more helpful to have a root examples folder. However, I'd argue that perhaps most of these things should either be learned through the documentation or available Jupyter Notebooks, e.g., where one could test out and learn how to use the package and the tools? The latter could be done with mybinderhttps://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fmybinder.org%2F&data=04%7C01%7Cfrancesca.l.bleken%40sintef.no%7C83f5ca90d4744d171cae08d97dbc0485%7Ce1f00f39604145b0b309e0210d8b32af%7C1%7C0%7C637679068749754252%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=NAnz%2B65uZwlWxqUr7PIQkDUNUDl5dmuPqTuZZ%2BYy7%2Bw%3D&reserved=0 or a page of simple setup instructions in the documentation for how to install and start a Jupyter server in the correct "demo/examples" folder location.

In this way the demonstrations and examples are consciously labeled as "documentation".

Also, what is the difference between demonstrations (demo) and examples here? Isn't it essentially the same thing? Or is "demo" more of an example to use multiple tools at once, where examples are tool-specific?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Femmo-repo%2FEMMO-python%2Fissues%2F193%23issuecomment-924840567&data=04%7C01%7Cfrancesca.l.bleken%40sintef.no%7C83f5ca90d4744d171cae08d97dbc0485%7Ce1f00f39604145b0b309e0210d8b32af%7C1%7C0%7C637679068749794048%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=rCw6QMVBffrSCEVpRDWLOtlSBFtV9zQvVfp2ylIosqk%3D&reserved=0, or unsubscribehttps://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FALPGAD3TT37HCOWYNXZ5YKDUDG4TRANCNFSM5CLMUICQ&data=04%7C01%7Cfrancesca.l.bleken%40sintef.no%7C83f5ca90d4744d171cae08d97dbc0485%7Ce1f00f39604145b0b309e0210d8b32af%7C1%7C0%7C637679068749813954%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=n3xeAUDbP389%2BvFgy56ZBtwVUpo4WZY5m50yHMXIq%2BU%3D&reserved=0. Triage notifications on the go with GitHub Mobile for iOShttps://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fapps.apple.com%2Fapp%2Fapple-store%2Fid1477376905%3Fct%3Dnotification-email%26mt%3D8%26pt%3D524675&data=04%7C01%7Cfrancesca.l.bleken%40sintef.no%7C83f5ca90d4744d171cae08d97dbc0485%7Ce1f00f39604145b0b309e0210d8b32af%7C1%7C0%7C637679068749843820%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=qlPF0hQ0yq5%2BEXysMzTnlzbsnZKevE%2FCfO5CLrHxDKo%3D&reserved=0 or Androidhttps://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fplay.google.com%2Fstore%2Fapps%2Fdetails%3Fid%3Dcom.github.android%26referrer%3Dutm_campaign%253Dnotification-email%2526utm_medium%253Demail%2526utm_source%253Dgithub&data=04%7C01%7Cfrancesca.l.bleken%40sintef.no%7C83f5ca90d4744d171cae08d97dbc0485%7Ce1f00f39604145b0b309e0210d8b32af%7C1%7C0%7C637679068749883650%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=QfX6%2FdaPGOxHMnASthUPbsBhf1rs0iAo0P59WHZ7J24%3D&reserved=0.