axone-protocol / docs Goto Github PK

Issue

The URL https://docs.okp4.network/academy, leads to a "404 page not found" error. Instead, it should be better to navigate users directly to the academy's welcome page at https://docs.okp4.network/academy/overview.

should use 5.0.0 instead of v5.0.0 because it doesn't work with this v prefixed version.

As part of the rebranding effort, we need to update all references of the okp4/okp4d Docker image to axone-protocol/axoned and all okp4d command references to axoned. This includes updating the Docker image name and command references in the documentation and configuration files. This task is related to the migration of okp4d to the new axoned repository (axone-protocol/axoned#616). The changes will be part of another PR.

The Norse font appears too bold when we use the Firefox navigator.

Firefox ❌

Safari ✅

Issue

The current website footer lacks certain elements for user navigation and overall site aesthetics.

Issue

To uphold a cohesive visual experience across our documentation, it's imperative that we maintain consistent font and illustration sizes.

Todo

Based on observations from @ManonPoint26 and @MdechampG:

• The font size in certain sections appears to be too small. Consider increasing it to 18px.
• Images within the whitepaper section appear larger than necessary. A reduction in their size would enhance readability.

Notes

• For the docusaurus syntax that specifies image sizes, refer to the example in: Hierarchy of Norms.

Issue

The markdown backstick (code section) is not displayed correctly. See: https://docs.okp4.network/tutorials/cli-1#okp4d-requirements.

There are a lot of commits like that, which are prone to induce unnecessary merge conflicts/rebases (incl. on PR #276).

Context

As our Docusaurus documentation continues to grow, we have incorporated a significant number of pages written in MDX format. To ensure that our MDX pages meet quality standards, we need to implement/setup an MDX linter into our CI workflow.

Scope

Introduce an MDX linter to the CI pipeline, similar to the one we already have for markdown files. The linter should analyze the MDX files during the CI process and provide feedback on adherence to style guidelines.

Todo

• Research available MDX linters and assess their compatibility for integration with our current CI, and check whether they can also be invoked from the command line.
• Create a new CI job named lint-mdx responsible for running the selected linter on all MDX files within the docs/ directory.
• Address any errors or issues identified by the linter, ensuring that the lint-mdx job produces successful outcomes (green status).
• Optionally, investigate the possibility of launching the linter execution via the yarn command (declared in the package.json file).

Issue

Build times are getting longer and longer.

Todo

Find ways to improve the build time, as the deployment pipeline is severely degraded.

Expected Behavior

Docusaurus is designed to provide a version selection widget, allowing users to choose the version of the documentation they are viewing (for versioned documentation). This functionality is intended to be consistent across all device sizes.

Current Behavior

• Issue on Small Devices: When viewing the documentation on devices with small screens (specifically, those with widths around or below the ~996px breakpoint), the version selection widget is not displayed. See the provided screenshots.
• Hamburger Menu: Additionally, the version selection widget is not integrated into the hamburger menu for easier access on smaller screens.

Visual Evidence

• Screenshot showcasing the presence of the widget on wide devices.

• Screenshot showcasing the missing widget on a small device.

• Screenshot showcasing the absence of the widget in the hamburger menu.

Steps to Reproduce

1. Access the documentation using a mobile phone.
2. Navigate to the specified URL: http://localhost:3000/ontology/schemas/credential-dataset-description.

Impact

This issue has a significant usability concern for users accessing the documentation on mobile devices or screens with lower resolution, as it prevents them from easily switching between documentation versions.

Issue

Currently, CoderabbitAI inspects all changed files in PRs, including those from generated documentation. This can be seen in PR #499.

Proposal

Similar to PR axone-protocol/axoned#644, update the CoderabbitAI configuration to exclude generated documentation from inspection. This should apply to the documentation provided by axoned, contracts, and ontology repositories.

Purpose

As a OKP4 builder, I would like to have a comprehensive documentation of the ontology, so that I can easily understand the concepts, relationships, and properties defined in the ontology. This documentation is commited in the project.

The generated documentation is aggregated in the OKP4 docusaurus documentation site.

Now that we have a basis of documentation, it would be good to make it more user-friendly.

Todo

• Make 1 page by VC schema
• Classify the VCs schemas:

Datasets VCs:

• Dataset description credential
• Governance description credential

Digital services VCs:

• Digital service description credential
• Digital service execution order credential
• Digital service execution result credential
• Governance description credential

Zones VCs:

• Zone description credential
• Governance description credential

• Add properties
• Add examples
• Add thesaurus