docs&refactor: clarity improvements #267
Conversation
maciejmajek
changed the title
…f the whoami package and provide additional steps for generated files inspection refactor(rai_cli.py): change argument names and paths in parse_whoami_package function to improve clarity and organization of generated files refactor(rai_whoami_node.py): update paths to robot constitution, identity, and URDF description files to reflect new directory structure for generated files
maciejmajek
force-pushed
the
docs/easier-whoami
branch
from
54136fd
to
60bcd75
Compare
… "Developer resources" for clarity docs(README.md): enhance description in Developer Resources section to provide more context on the Developer Guide
…etter visibility and emphasis in documentation
…arity by adding line breaks between steps
…he Text HMI to enhance developer experience docs(developer_guide): update section numbering to reflect the addition of the new testing instructions
… directory structure in tests
…r initialization in ROS2Agent for better clarity and usability
| @@ -180,7 +180,7 @@ Please take a look at [Q&A](https://github.com/RobotecAI/rai/discussions/categor | |||
|
|
|||
| ### Developer Resources | |||
|
|
|||
| See our [Developer Guide](docs/developer_guide.md). | |||
| See our [Developer Guide](docs/developer_guide.md) for a deeper dive into RAI, including instructions on creating a configuration specifically for your robot. | |||
There was a problem hiding this comment.
I suggest maybe even getting Create your own robot at top level, followed by developers resources
There was a problem hiding this comment.
This is a good idea, let me introduce these changes in the next week, during docs refactoring 🙇🏼♂️
| args = parser.parse_args() | ||
| save_dir = args.output if args.output is not None else args.documentation_root | ||
| save_dir = Path(args.whoami_package_root) / "description" / "generated" |
There was a problem hiding this comment.
Ideally, this should adhere to the source / build divide and land in the installation /share folder. I understand there's an issue of cost and, to a lesser degree, build time. But this should not be in sources most likely
There was a problem hiding this comment.
I actually think otherwise. User should be able to modify the generated files to fine-tune them. Creating new identity/vector database every run could increase non-deterministic behaviors.
There was a problem hiding this comment.
Keeping it as a build artifact does not mean creating a new identity vector database every run, correct?
There was a problem hiding this comment.
Correct. Either way I would like to give the users ability to view, modify and git these files. I can agree to a certain point that these files could be seen as build artifacts but I believe, that the current solution is better. Adhering to ROS 2 standard in this case reduces the user friendliness.
maciejmajek
changed the title
Purpose
Improve clarity and simplify the "whoami" documentation, which was previously confusing and difficult to follow.
Proposed Changes
Issues
Testing
Tested using docs/create_robots_whoami.md ✅