Add webpack related theme development documentation #100
Conversation
|
Issue #100 🎉. |
README.md
Outdated
| Install via conda: | ||
|
|
||
| ```bash | ||
| conda install |
There was a problem hiding this comment.
Indeed, well spotted.
README.md
Outdated
| conda install | ||
| ``` | ||
|
|
||
| Install alternative: https://classic.yarnpkg.com/en/docs/install#mac-stable. |
There was a problem hiding this comment.
Maybe remove the mac specific anchor?
There was a problem hiding this comment.
Good point, missed it over pasting.
| - ./src/js/theme.js | ||
| - ./src/scss/theme.scss | ||
| - ./docs/\*\*/\*.rst | ||
| - ./docs/\*\*/\*.py |
There was a problem hiding this comment.
Are the py files inside pandas_sphinx_theme also whatched?
And the html layouts?
There was a problem hiding this comment.
Currently not, but is is possible.
| ```bash | ||
| yarn build:production | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Maybe mention that it is needed to run either build:dev or build:production before committing, as the generated files are included and tracked in the repo?
There was a problem hiding this comment.
Good suggestion, will add this.
There was a problem hiding this comment.
I suppose that certainly the html layouts make sense to also watch?
|
|
||
| ```bash | ||
| yarn install | ||
| ``` |
There was a problem hiding this comment.
This you can run initially, but suppose you already did this, and at some point we update the dependencies (or you want to ensure you still have all up to date dependencies), what to do then? The same command?
There was a problem hiding this comment.
Indeed the same command. Yarn writes away its exact installed dependencies in the yarn.lock file. Even loosely defined dependencies won't mess up new installations because the lock file is your explicit reference.
There was a problem hiding this comment.
Can you mention this explicitly that if the dependencies were updated, you need to run "yarn install" again?
Co-Authored-By: Chris Holdgraf <[email protected]>
Co-Authored-By: Joris Van den Bossche <[email protected]>
Co-Authored-By: Joris Van den Bossche <[email protected]>
Co-Authored-By: Joris Van den Bossche <[email protected]>
hoetmaaiers
force-pushed
the
feature/theme-dev-documentation
branch
from
71ff0ed to
b808b86
Compare
|
I think without any other remarks, this PR can be merged? |
pandas_sphinx_theme/layout.html
Outdated
|
|
||
| {% extends "basic/layout.html" %} {# prev/next buttons #} {% macro | ||
| prev_next(prev, next, prev_title='', next_title='') %} {%- if prev %} | ||
| <a |
There was a problem hiding this comment.
Question here: did you use some kind of html auto-formatter? Which would be a good idea, but it seems it didn't handle the jinja templating very well?
There was a problem hiding this comment.
Hi Joris,
Indeed the autoformatter I use (Prettier) is not playing friendly with Jinja. Currently this is disabled in new push on this PR.
|
This will need a merge from master or rebase now the other PR is merged. I might have missed the discussion elsewhere, but was there a specific reason for the theme.css/js -> index.css/js rename? |
|
Can I give my +1 on merging this sooner than later? As someone who has recently tried to figure out the yarn/webpack build process I would benefit from documentation :-) for index vs. theme, I think index is more common in the web-dev community, while theme is more common in the sphinx community. I'm happy w/ either |
|
The merge is done. What @choldgraf says is true, in web-dev community the entry point is commonly named |
|
No experience here, but "index" might also be more common in projects that are "final" apps, not libraries. While this theme has still downstream users, so is in some way a library as well. Anyway, my main concern is what is easiest to understand for users of the theme. I know that I regularly look at the website through firefox developer tools to eg check where a certain styling element is coming from (is it inherited from bootstrap, or from base sphinx, or is it defined somewhere in the theme css?) And then it is useful that the different css files that are included in the html have descriptive names (eg bootstrap.min.css, pygments.css). In that idea, it might actually even be better to use a longer name like "pydata-bootstrap-sphinx.css" (once we decide on a final name ... ;-)) |
|
But let's the naming discussion not hold up better docs! |
|
Thanks a lot! |
|
Shall we create an issue to discuss the entry point naming? index.css vs theme.css |
Documentation explaining how theme development should be done. Taking into account all remarks made in #88.