Enhance Developer guide and experience #7218
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #7218 +/- ##
=======================================
Coverage 82.25% 82.25%
=======================================
Files 331 331
Lines 49460 49461 +1
=======================================
+ Hits 40682 40684 +2
+ Misses 8778 8777 -1 ☔ View full report in Codecov by Sentry. |
|
|
||
| To be able to run cells interactively you need `pyodide` server, this can be ran with: | ||
| ```bash | ||
| pixi run _docs-build-api-reference |
There was a problem hiding this comment.
I've never understood the docs build flow before. But now I think I do. Making the sub tasks more visible and giving them more readable names will help a me lot. I believe it will help others too.
There was a problem hiding this comment.
For example all the broken links we have. Now I think I now better how to fix it because I understand how the nbsite build will see the examples.
There was a problem hiding this comment.
Making the sub tasks more visible ... I believe it will help others too.
I explicitly made them non-visible. The biggest problem is that one of the tasks takes 95 % or more of the time; this should be improved at a fundamental level with how nbsite builds the documentation.
Two things should be considered when working with development tools: using them and debugging/fixing problems with them.
Most contributors should "just" use the development tool, which should be as easy as possible. This is why it is one command and hides the subcommands. Most users should not need to remember (or even know) five subcommands and which order they should be run in.
You are having problems debugging or fixing a problem caused by the development tool you are using, which is great! But it is, or should be, limited to a handful of people.
This suggestion falls into the latter category and could, in my opinion, confuse new developers more than help them.
... and giving them more readable names will help a me lot.
No problem with better names.
There was a problem hiding this comment.
But there is no need to spend time on creating api Gallery or Pyodide output if I'm working on some markdown document.
There was a problem hiding this comment.
Agree with that, that said only certain subtasks should be pulled out, I'd say currently this makes sense:
docs-build-sphinxdocs-build-pyodide-gallery
and then I'd ideally to have a docs-preview task so you can preview individual docs pages without building the entire sphinx site.
| @@ -99,6 +126,8 @@ pixi run -e test-ui install | |||
|
|
|||
| ::: | |||
|
|
|||
| You can find the names of the environments in the **pixi.toml** file. | |||
There was a problem hiding this comment.
Seems better to recommend running pixi info and pixi task list.
| 1. Go to [github.com/holoviz/panel](https://github.com/holoviz/panel) | ||
| 2. [Fork the repository](https://docs.github.com/en/get-started/quickstart/contributing-to-projects#forking-a-repository) | ||
| 3. Run in your terminal: `git clone https://github.com/<Your Username Here>/panel` | ||
|
|
||
| ::: | ||
|
|
||
| :::{tab-item} Core Contributor |
There was a problem hiding this comment.
I feel that if you are a core contributor, you have shown your worth and do not need guidance on how to clone a repo.
This page is meant for new contributors, not experienced ones.
There was a problem hiding this comment.
I agree that you know how to do it.
But as any contributor you go here to get installed. Its multiple steps and they change over time.
It is convenient you can Copy into terminal instead of spdnding additional time compsing commands.
| Now navigate to the root of the `panel` project: | ||
|
|
||
| ```bash | ||
| cd panel |
There was a problem hiding this comment.
If you can't cd into a directory, you are likely unable to contribute 🙃
There was a problem hiding this comment.
But for example if you are leading a sprint at a conference some people with minimal technical skills will join to not only contribute, but to learn.
I would argue we should make the developer guide as beginner friendly and explicit as possible.
|
|
||
| To be able to run cells interactively you need `pyodide` server, this can be ran with: | ||
| ```bash | ||
| pixi run _docs-build-api-reference |
There was a problem hiding this comment.
Making the sub tasks more visible ... I believe it will help others too.
I explicitly made them non-visible. The biggest problem is that one of the tasks takes 95 % or more of the time; this should be improved at a fundamental level with how nbsite builds the documentation.
Two things should be considered when working with development tools: using them and debugging/fixing problems with them.
Most contributors should "just" use the development tool, which should be as easy as possible. This is why it is one command and hides the subcommands. Most users should not need to remember (or even know) five subcommands and which order they should be run in.
You are having problems debugging or fixing a problem caused by the development tool you are using, which is great! But it is, or should be, limited to a handful of people.
This suggestion falls into the latter category and could, in my opinion, confuse new developers more than help them.
... and giving them more readable names will help a me lot.
No problem with better names.
| @@ -209,6 +247,7 @@ You will likely want to check out the | |||
|
|
|||
| - [Dev version of Panel Site](https://holoviz-dev.github.io/panel) | |||
| - Use this to explore new, not yet released features and docs | |||
| - See which branch is currently deployed [here](https://github.com/holoviz/panel/actions/workflows/docs.yaml) | |||
There was a problem hiding this comment.
You need to know what you are looking for to see what branch is deployed as the docs can be built in a dry run option.
|
I can see we don't agree and thus it does not make sense to try to push for what I believe are improvements. |
Closes #7217 and #7220