Skip to content

Fix: reorganize index structure for users #188

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Mar 20, 2024
Merged

Fix: reorganize index structure for users #188

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
78ff4dd
make index page match toctree structure
sneakers-the-rat Feb 27, 2024
e0f3fdb
make more links to documentation and tests sections
sneakers-the-rat Feb 27, 2024
873ffdb
Merge branch 'main' into index-structure
sneakers-the-rat Mar 19, 2024
3ebfadf
fix code of conduct link
sneakers-the-rat Mar 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion _static/pyos.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ h1 {
color: var(--pyos-h1-color);
}
h2 {
margin-top: 80px;
margin-top: 1em;
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sneakers-the-rat we can merge this but i have a question. i see

em, px which is fixed and rem used. and i never know when to use what approach. i'm curious what your thoughts are!! :) just a learning moment for me.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Basically the way I think about it is px is rarely the "right" thing for responsive because what really matters most of the time is relative size - 1px is very different as a proportion of screen on different displays. But it is definitely the easiest and most predictable to reason about.

em and rem are both relative units, but em is relative to the current (parent) font size and REM is relative to the root size. So REM when you might use the class in multiple contexts but want the thing to look the same, em when you would want it to scale. I just default em.

With padding/margins specifically I think em is easier to think about bc I am looking at the page and can eyeball "I need about a text height space there" vs. I have no idea what that is in px. And the scale isnt necessarily linear but the spacing you need scales with the text size anyway so you need to do fewer fine tuning things over time. When you see a page where all the spacings are subtly wonky its usually because the sizes use px/other absolute unit (and also maybe not using sass in an era before easy css variables and calc)

}

h3 {
Expand Down
78 changes: 68 additions & 10 deletions index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ Community docs

Publish your docs
```
## _new_ Tutorial Series: How to Create a Python Package
## _new_ Tutorial Series
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## _new_ Tutorial Series
## _new_ Tutorial Series: Create a Python package

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about a middle ground. i just know that header tags matter in search results. And people skim

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Either way! All these are always just suggestions.


The how to create a Python package tutorial series is being developed
by the community now! Join our community review process or watch development of these tutorials in our [Github repo here](https://github.com/pyOpenSci/python-package-guide).
Expand Down Expand Up @@ -100,7 +100,7 @@ by the community now! Join our community review process or watch development of
:::::


## Python packaging ecosystem overview & best practices
## Packaging
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Packaging
## Python Packaging for Scientists


Learn about Python packaging best practices. You will also get to know the
the vibrant ecosystem of packaging tools that are available to help you with your Python packaging needs.
Expand Down Expand Up @@ -135,31 +135,90 @@ Learn about best practices for:

:::
::::
:::::

## Documentation

:::::{grid} 1 1 2 2
:class-container: text-center
:gutter: 3

::::{grid-item}
:::{card} ✨ Write & Publish Docs ✨
:::{card} ✨ Write The Docs ✨
:class-card: left-aligned

* [Create documentation for your users](/documentation/write-user-documentation/intro)
* [Core files to include in your package repository](/documentation/repository-files/intro)
* [Write tutorials to show how your package is used](/documentation/write-user-documentation/create-package-tutorials)
:::
::::

::::{grid-item}
:::{card} ✨ Developer Docs ✨
:class-card: left-aligned

* [Create documentation for collaborating developers](/documentation/repository-files/contributing-file)
* [Write a development guide](/documentation/repository-files/development-guide)
:::
::::

::::{grid-item}
:::{card} ✨ Document For A Community ✨
:class-card: left-aligned

* [Writing a README file](/documentation/repository-files/readme-file-best-practices)
* [Set norms with a Code of Conduct](/documentation/repository-files/code-of-conduct-file)
* [License your package](/documentation/repository-files/license-files)
:::
::::

::::{grid-item}
:::{card} ✨ Publish Your Docs ✨
:class-card: left-aligned

* [How to publish your docs](/documentation/hosting-tools/intro)
* [Using Sphinx](/documentation/hosting-tools/intro)
* [Markdown, MyST, and ReST](/documentation/hosting-tools/myst-markdown-rst-doc-syntax)
* [Host your docs on Read The Docs or Github Pages](/documentation/hosting-tools/publish-documentation-online)
:::
::::

:::::

## Tests

*We are actively working on this section. [Follow development here.](https://github.com/pyOpenSci/python-package-guide)*

:::::{grid} 1 1 2 2
:class-container: text-center
:gutter: 3

::::{grid-item}
:::{card} ✨ Tests for your Python package ✨
:class-card: left-aligned

* [Intro to testing](tests/index.md)
* [Write tests](tests/write-tests)
* [Types of tests](tests/test-types)
:::
::::

::::{grid-item}
:::{card} ✨ Run your tests ✨
:class-card: left-aligned

* [Run tests locally](tests/run-tests)
* [Run tests in CI](tests/tests-ci)

*We are actively working on this section. [Follow development here.](https://github.com/pyOpenSci/python-package-guide)*
:::
::::
:::::

## Contributing

:::::{grid} 1 1 2 2
:class-container: text-center
:gutter: 3


::::{grid-item}
:::{card} ✨ Code style & Format ✨
Expand Down Expand Up @@ -228,20 +287,19 @@ This is a living guide that is updated as tools and best practices evolve in the
Tutorials <tutorials/intro>
```


```{toctree}
:hidden:
:caption: Documentation
:caption: Packaging

Documentation <documentation/index>
Packaging <package-structure-code/intro>

```

```{toctree}
:hidden:
:caption: Packaging
:caption: Documentation

Packaging <package-structure-code/intro>
Documentation <documentation/index>

```

Expand Down