Skip to content
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

Jump to bottom

Améliorations diverses des pages de doc des règles #354

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Améliorations diverses des pages de doc des règles #354

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ee837d1
New contribution section in the documentation RulePage
laem Jan 16, 2023
6d8ef01
Move the question rule attribute display to a new section
laem Jan 17, 2023
c8dcbb7
More props to the References component
laem Jan 17, 2023
04d8928
Move the references check in the References component
laem Jan 17, 2023
52bcd1b
Let the user display a visualisation block under the description, before
laem Jan 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 2 additions & 0 deletions packages/react-ui/source/contexts.tsx
View file
Open in desktop
Expand Up @@ -24,6 +24,7 @@ export type SupportedRenderers = {
*/
Text?: ComponentType<{ children: string }>
References?: typeof References
VisualisationBlock?: React.ComponentType
Copy link
Member

Choose a reason for hiding this comment

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

J'ajouterai un peu de tsdoc ici pour préciser à quoi sert VisualisationBlock. De ce que je comprends, il s'agit d'un composant custom à ajouter dans les pages règles entre la description et l'explication des calculs. Si c'est bien ça, je propose un tout petit ajout : passer en prop le dottedName de la règle courante, au cas où l'on souhaite avoir une logique d'affichage différente en fonction de la règle.

/**
* Accordion used for developer documentation.
*/
Expand Down Expand Up @@ -54,6 +55,7 @@ export const defaultRenderers = (renderers: SupportedRenderers = {}) => {
Code,
Accordion,
Link: DefaultLinkRenderer,
VisualisationBlock: undefined,
}

return Object.fromEntries(
Expand Down
45 changes: 25 additions & 20 deletions packages/react-ui/source/rule/References.tsx
View file
Open in desktop
@@ -1,32 +1,37 @@
import { capitalise0 } from 'publicodes'

type ReferencesProps = {
references: Record<string, string>
references: Record<string, string> | undefined
rawNode: Object
}

export default function References({ references }: ReferencesProps) {
if (!references) return null
return (
<ul>
{Object.entries(references).map(([name, link]) => (
<li
style={{
display: 'flex',
alignItems: 'center',
}}
key={name}
>
<a
href={link}
target="_blank"
<section>
<h3>Références</h3>
<ul>
{Object.entries(references).map(([name, link]) => (
<li
style={{
marginRight: '1rem',
display: 'flex',
alignItems: 'center',
}}
key={name}
>
{capitalise0(name)}
</a>
<span className="ui__ label">{link}</span>
</li>
))}
</ul>
<a
href={link}
target="_blank"
style={{
marginRight: '1rem',
}}
>
{capitalise0(name)}
</a>
<span className="ui__ label">{link}</span>
Copy link
Member

Choose a reason for hiding this comment

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

Je crois que l'on peut supprimer les ui__ label qui ne sont plus utilisés.

</li>
))}
</ul>
</section>
)
}
46 changes: 39 additions & 7 deletions packages/react-ui/source/rule/RulePage.tsx
View file
Open in desktop
Expand Up @@ -36,6 +36,14 @@ type RulePageProps = {
mobileMenuPortalId?: string
openNavButtonPortalId?: string
showDevSection?: boolean
contributionLink?: {
repository: string
// e.g. repository: 'datagir/nosgestesclimat',
Copy link
Member

Choose a reason for hiding this comment

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

Cela peut passer en tsdoc également pour en bénéficier directement dans l'IDE lorsqu'on autocomplete les props.

directory: string
// e.g. directory: 'data',
title?: string
text?: string
}
}

export default function RulePage({
Expand All @@ -50,6 +58,7 @@ export default function RulePage({
mobileMenuPortalId,
openNavButtonPortalId,
showDevSection = true,
contributionLink,
}: RulePageProps) {
const currentEngineId = new URLSearchParams(window.location.search).get(
'currentEngineId'
Expand Down Expand Up @@ -81,6 +90,7 @@ export default function RulePage({
mobileMenuPortalId={mobileMenuPortalId}
openNavButtonPortalId={openNavButtonPortalId}
showDevSection={showDevSection}
contributionLink={contributionLink}
/>
</RenderersContext.Provider>
</BasepathContext.Provider>
Expand All @@ -100,6 +110,7 @@ type RuleProps = {
| 'mobileMenuPortalId'
| 'openNavButtonPortalId'
| 'showDevSection'
| 'contributionLink'
>

function Rule({
Expand All @@ -112,9 +123,10 @@ function Rule({
mobileMenuPortalId,
openNavButtonPortalId,
showDevSection,
contributionLink,
}: RuleProps) {
const baseEngine = useEngine()
const { References, Text } = useContext(RenderersContext)
const { References, Text, VisualisationBlock } = useContext(RenderersContext)

const useSubEngine =
subEngineId && baseEngine.subEngines.length >= subEngineId
Expand Down Expand Up @@ -147,9 +159,15 @@ function Rule({
<Article>
<DottedNameContext.Provider value={dottedName}>
<RuleHeader dottedName={dottedName} />
{question && (
Copy link
Member

Choose a reason for hiding this comment

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

Ce n'est pas bizarre d'afficher la question à chaque fois juste au-dessus de la description ? Cela ne donne-t-il pas l'impression que la description est une réponse à la question ? (c'est une vraie interrogation, peut-être que pas du tout)

Ceci étant dit, sur le principe, je suis pour afficher la question dans la documentation.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Je me suis posé un peu la même question, pour la page https://pages-doc-rapides--nosgestesclimat.netlify.app/documentation/alimentation/plats j'ai eu du mal à comprendre la relation entre la description et la question 🤔

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

image

En effet, suite à une remarque de @Clemog j'ai ajouté un label "aide à la saisie" quand il s'agit d'une question.

<section id="documentation-rule-question">
<Text>{question}</Text>
</section>
)}
<section>
<Text>{description || question || ''}</Text>
<Text>{description || ''}</Text>
</section>
{VisualisationBlock && <VisualisationBlock />}

<p style={{ fontSize: '1.25rem', lineHeight: '2rem' }}>
Valeur : {formatValue(rule, { language })}
Expand Down Expand Up @@ -209,11 +227,25 @@ function Rule({
</div>
</>
)}
{rule.rawNode.références && References && (
<>
<h3>Références</h3>
<References references={rule.rawNode.références} />
</>
<References
references={rule.rawNode.références}
rawNode={rule.rawNode}
/>

{contributionLink && ( // Feature only implemented for github for now, don't hesitate to implement Gitlab and others
<div>
<h3>
{contributionLink.title ||
`Une erreur, une idée d'amélioration ?`}
</h3>
<a
href={`https://github.com/search?q=${encodeURIComponent(
`repo:${contributionLink.repository} "${dottedName}:"`
)} path:${contributionLink.directory}&type=code`}
>
{contributionLink.text || `✏️ Contribuer à cette page`}
</a>
</div>
)}
<br />

Expand Down