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

Use docify export for parachain template hardcoded configuration and embed it in its README #6333

Closed
iulianbarbu opened this issue Nov 1, 2024 · 4 comments
Closed

Use docify export for parachain template hardcoded configuration and embed it in its README #6333

iulianbarbu opened this issue Nov 1, 2024 · 4 comments
Assignees
@seemantaggarwal
Labels
C1-mentor A task where a mentor is available. Please indicate in the issue who the mentor could be. T17-Templates This PR/Issue is related to templates

Comments

@iulianbarbu
Copy link
Contributor

More details posted here: https://github.com/paritytech/polkadot-sdk/pull/5954/files/8b4884dc8a9d60d09d61b08ada0e645121c0d6b8#r1825695159. The idea is to keep parachain-template README.md in sync with the hardcoded configuration set in the Rust code.
@iulianbarbu iulianbarbu added the T17-Templates This PR/Issue is related to templates label Nov 1, 2024
@iulianbarbu iulianbarbu self-assigned this Nov 1, 2024
@iulianbarbu iulianbarbu mentioned this issue Nov 1, 2024
Merged
3 tasks
@iulianbarbu iulianbarbu moved this to Milestone 1 in Polkadot Omni Node Nov 27, 2024
@seemantaggarwal
Copy link
Contributor

Had a word with @iulianbarbu about this. We will divide this into three parts:

  1. Creating a docify template to generate a Readme in parachain template
  2. mirror the current state of Readme.md through the docify tempalte
  3. Replace the hardcoded value during compile time
  4. Test by changing the value, not a commit

We will track each step through this PR only

@seemantaggarwal
Copy link
Contributor

Important example to look at
substrate/bin/utils/chain-spec-builder

This already uses a docify, I will study and understand how the template works here, and then use the knowledge gained to mirror it for the parachain template

@iulianbarbu
Copy link
Contributor Author

iulianbarbu commented Jan 8, 2025 •
edited
Loading

Following up on a topic I discussed previously with @seemantaggarwal , and putting my finding for reference here: I recall why we added the dollar sign ($) for $runtime_path example I showed you from chain-spec-builder.

We also run tests for the export_content sections that can be found in chain-spec-builder crate (so that we get testable documentation which is kept up to date given these tests run in CI). The $ is needed at runtime not by docify but by cmd_lib crate (used to execute bash like commands in the rust tests). It interpolates variables that are in scope into the bash-like commands: e.g. https://docs.rs/cmd_lib/latest/cmd_lib/#macros-to-run-external-commands. We shouldn't need a similar test for the scope of this issue, only testing the exported const value changes in the readme manually after it is modified in the code.

@iulianbarbu iulianbarbu added the C1-mentor A task where a mentor is available. Please indicate in the issue who the mentor could be. label Jan 8, 2025
seemantaggarwal added a commit that referenced this issue Jan 8, 2025
@seemantaggarwal
initial docify readme with some content #6333
dd6429e
@seemantaggarwal seemantaggarwal mentioned this issue Jan 8, 2025
Merged
github-merge-queue bot pushed a commit that referenced this issue Jan 20, 2025
@seemantaggarwal @iulianbarbu
Use docify export for parachain template hardcoded configuration and …
4937f77 
…embed it in its README #6333 (#7093)

Use docify export for parachain template hardcoded configuration and
embed it in its README #6333

Docify currently has a limitation of not being able to embed a
variable/const in its code, without embedding it's definition, even if
do something in a string like

"this is a sample string ${sample_variable}"

It will embed the entire string 
"this is a sample string ${sample_variable}"
without replacing the value of sample_variable from the code

Hence, the goal was just to make it obvious in the README where the
PARACHAIN_ID value is coming from, so a note has been added at the start
for the same, so whenever somebody is running these commands, they will
be aware about the value and replace accordingly.

To make it simpler, we added a 
rust ignore block so the user can just look it up in the readme itself
and does not have to scan through the runtime directory for the value.

---------

Co-authored-by: Iulian Barbu <14218860+iulianbarbu@users.noreply.github.com>
Nathy-bajo pushed a commit to Nathy-bajo/polkadot-sdk that referenced this issue Jan 21, 2025
@seemantaggarwal @iulianbarbu @Nathy-bajo
Use docify export for parachain template hardcoded configuration and …
400c815 
…embed it in its README paritytech#6333 (paritytech#7093)

Use docify export for parachain template hardcoded configuration and
embed it in its README paritytech#6333

Docify currently has a limitation of not being able to embed a
variable/const in its code, without embedding it's definition, even if
do something in a string like

"this is a sample string ${sample_variable}"

It will embed the entire string 
"this is a sample string ${sample_variable}"
without replacing the value of sample_variable from the code

Hence, the goal was just to make it obvious in the README where the
PARACHAIN_ID value is coming from, so a note has been added at the start
for the same, so whenever somebody is running these commands, they will
be aware about the value and replace accordingly.

To make it simpler, we added a 
rust ignore block so the user can just look it up in the readme itself
and does not have to scan through the runtime directory for the value.

---------

Co-authored-by: Iulian Barbu <14218860+iulianbarbu@users.noreply.github.com>
Nathy-bajo pushed a commit to Nathy-bajo/polkadot-sdk that referenced this issue Jan 21, 2025
@seemantaggarwal @iulianbarbu @Nathy-bajo
Use docify export for parachain template hardcoded configuration and …
7492626 
…embed it in its README paritytech#6333 (paritytech#7093)

Use docify export for parachain template hardcoded configuration and
embed it in its README paritytech#6333

Docify currently has a limitation of not being able to embed a
variable/const in its code, without embedding it's definition, even if
do something in a string like

"this is a sample string ${sample_variable}"

It will embed the entire string 
"this is a sample string ${sample_variable}"
without replacing the value of sample_variable from the code

Hence, the goal was just to make it obvious in the README where the
PARACHAIN_ID value is coming from, so a note has been added at the start
for the same, so whenever somebody is running these commands, they will
be aware about the value and replace accordingly.

To make it simpler, we added a 
rust ignore block so the user can just look it up in the readme itself
and does not have to scan through the runtime directory for the value.

---------

Co-authored-by: Iulian Barbu <14218860+iulianbarbu@users.noreply.github.com>
mordamax pushed a commit to paritytech-stg/polkadot-sdk that referenced this issue Jan 21, 2025
@seemantaggarwal @iulianbarbu @mordamax
Use docify export for parachain template hardcoded configuration and …
2abe6ba 
…embed it in its README paritytech#6333 (paritytech#7093)

Use docify export for parachain template hardcoded configuration and
embed it in its README paritytech#6333

Docify currently has a limitation of not being able to embed a
variable/const in its code, without embedding it's definition, even if
do something in a string like

"this is a sample string ${sample_variable}"

It will embed the entire string 
"this is a sample string ${sample_variable}"
without replacing the value of sample_variable from the code

Hence, the goal was just to make it obvious in the README where the
PARACHAIN_ID value is coming from, so a note has been added at the start
for the same, so whenever somebody is running these commands, they will
be aware about the value and replace accordingly.

To make it simpler, we added a 
rust ignore block so the user can just look it up in the readme itself
and does not have to scan through the runtime directory for the value.

---------

Co-authored-by: Iulian Barbu <14218860+iulianbarbu@users.noreply.github.com>
mordamax pushed a commit to paritytech-stg/polkadot-sdk that referenced this issue Jan 22, 2025
@seemantaggarwal @iulianbarbu @mordamax
Use docify export for parachain template hardcoded configuration and …
e9c8ddb 
…embed it in its README paritytech#6333 (paritytech#7093)

Use docify export for parachain template hardcoded configuration and
embed it in its README paritytech#6333

Docify currently has a limitation of not being able to embed a
variable/const in its code, without embedding it's definition, even if
do something in a string like

"this is a sample string ${sample_variable}"

It will embed the entire string 
"this is a sample string ${sample_variable}"
without replacing the value of sample_variable from the code

Hence, the goal was just to make it obvious in the README where the
PARACHAIN_ID value is coming from, so a note has been added at the start
for the same, so whenever somebody is running these commands, they will
be aware about the value and replace accordingly.

To make it simpler, we added a 
rust ignore block so the user can just look it up in the readme itself
and does not have to scan through the runtime directory for the value.

---------

Co-authored-by: Iulian Barbu <14218860+iulianbarbu@users.noreply.github.com>
@kianenigma
Copy link
Contributor

closed in #7093

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@seemantaggarwal seemantaggarwal

Labels
C1-mentor A task where a mentor is available. Please indicate in the issue who the mentor could be. T17-Templates This PR/Issue is related to templates
Projects
Polkadot Omni Node
Status: Milestone 1
Milestone
No milestone
Development

No branches or pull requests
3 participants
@kianenigma @iulianbarbu @seemantaggarwal