From 7ba64e97e48d5d1939854b334816f911e65e66a6 Mon Sep 17 00:00:00 2001 From: NateWilliams2 Date: Fri, 19 Apr 2024 14:33:06 -0400 Subject: [PATCH] Add readme template --- docs/Contributing/readme-template.md | 131 +++++++++++++++++++++++++++ sidebar.js | 71 ++++++++------- 2 files changed, 167 insertions(+), 35 deletions(-) create mode 100644 docs/Contributing/readme-template.md diff --git a/docs/Contributing/readme-template.md b/docs/Contributing/readme-template.md new file mode 100644 index 000000000..ef9f9d93a --- /dev/null +++ b/docs/Contributing/readme-template.md @@ -0,0 +1,131 @@ +# Readme Template + +Please use this template when creating readme files for new Vocdoni repositories. This is meant to serve as a guide, rather than a rigid rule; adapt it as necessary. Replace all the instances of `REPO_NAME` with the name of your repository, and fill-in the contents of every `\[bracketed\] item. If you add new sections, make sure to update the table of contents. +:::note +Some features are displayed differently on this site than they will be when rendered as standard markdown. For example, the following logo and badges are centered when displayed on Github. +::: + +

+ +

+ + +![GitHub commit activity (main)](https://img.shields.io/github/commit-activity/m/vocdoni/REPO_NAME) +[![GitHub issues](https://img.shields.io/github/issues/vocdoni/REPO_NAME)](https://github.com/vocdoni/REPO_NAME/issues) +[![Join Discord](https://img.shields.io/badge/discord-join%20chat-blue.svg)](https://discord.gg/xFTh8Np2ga) +[![Twitter Follow](https://img.shields.io/twitter/follow/vocdoni.svg?style=social&label=Follow)](https://twitter.com/vocdoni) + + + +
+ Vocdoni is the first universally verifiable, censorship-resistant, anonymous, and self-sovereign governance protocol.
+ Our main aim is a trustless voting system where anyone can speak their voice and where everything is auditable.
+ We are engineering building blocks for a permissionless, private and censorship resistant democracy. +
+ Explore the developer portal ยป +
+

More About Us

+ Vocdoni Website + | + Web Application + | + Blockchain Explorer + | + MIT Law Publication + | + Contact Us +
+

Key Repositories

+ Vocdoni Node + | + Vocdoni SDK + | + UI Components + | + Application UI + | + Census3 +
+ +# \[REPO_NAME\] + +This repository is \[description\] +It is written in \[language\] and can be used with \[tools\] to do \[purpose\] +The latest release is available at \[release-tag\] + +The best place to learn about using \[REPO_NAME\] is the [developer portal](https://developer.vocdoni.io/). + +### Table of Contents +- [Getting Started](#getting-started) +- [Reference](#reference) +- [Examples](#examples) +- [Preview](#preview) +- [Disclaimer](#disclaimer) +- [Contributing](#contributing) +- [License](#license) + + +## Getting Started + +\[Instructions for installing / running / using the code. If this is available at the developer portal, link here instead. Add any tutorials here as well.\] + +## Reference + +\[If this is a library or otherwise documented repo, link to the documentation. Documentation source-of-truth should be within the developer-portal, not this readme file.\] + +## Examples + +\[Provide links to our production code or basic examples to show how to use the software in this repo\] + +## Preview + +\[Add links to this code in use, if it exists.\] + +## Disclaimer + +\[The code in this repo\] is WIP. Please beware that it can be broken at any time if the release is `alpha` or `beta`. We encourage you to review this repository and the developer portal for any changes. + +## Contributing + + +While we welcome contributions from the community, we do not track all of our issues on Github and we may not have the resources to onboard developers and review complex pull requests. That being said, there are multiple ways you can get involved with the project. + +- If you have a simple bug or feature request, please submit an issue. We have many repositories, so please try to submit your issue to the relevant code base (eg. protocol feature request => [vocdoni-node](https://github.com/vocdoni/vocdoni-node), UI integration bugs => [ui-components](https://github.com/vocdoni/ui-components)). +- For simpler and more accessible contributions that should be possible without much onboarding, search this repo and others for issues that have the [help-wanted](https://github.com/vocdoni/REPO_NAME/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) or [good-first-issue](https://github.com/vocdoni/REPO_NAME/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) tags. + - Fork the Project + - Create your Feature Branch (`git checkout -b feature/yourFeature`) + - Commit your Changes (`git commit -m 'Add some yourFeature'`) + - Push to the Branch (`git push origin feature/yourFeature`) + - Open a Pull Request +- For more complex feature requests, or if you would like to contribute further, please reach out on our [discord](https://chat.vocdoni.io) support channel. + +## License + +This repository is licensed under \[license\](./LICENSE) + + + + Vocdoni API Typescript SDK + Copyright (C) 2022 Vocdoni Roots MCU + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU Affero General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . + diff --git a/sidebar.js b/sidebar.js index e6a0d7ac0..b14d812ad 100644 --- a/sidebar.js +++ b/sidebar.js @@ -3,67 +3,68 @@ const sidebarLabelOrder = { 'Vocdoni SDK': 1, 'Vocdoni API': 2, 'UI Components': 3, - 'Vocdoni Protocol': 4 // Last -} + 'Vocdoni Protocol': 4, + Contributing: 5, // Last +}; const sdkSidebarIDOrder = { 'sdk/reference/sdk-reference': -1, // First // All other elements are 0 by default - 'sdk/reference/changelog': 1 // Last -} + 'sdk/reference/changelog': 1, // Last +}; // Removes autogenerated API sidebar- this is broken. -function skipAPI (items) { +function skipAPI(items) { return items.filter(({label}) => { return ( // Exclude vocdoni-api folder, this folder needs swagger-generated sidebar label != 'vocdoni-api' - ) - }) + ); + }); } -function sortItems (items) { +function sortItems(items) { // Sort sidebar items by label according to sidebarLabelOrder return items.sort((i1, i2) => { return ( (sidebarLabelOrder[i1.label] || 0) - (sidebarLabelOrder[i2.label] || 0) - ) - }) + ); + }); } // Adds api sidebar items from './docs/vocdoni-api/sidebar.js', filters out index file -function addAPI (items) { +function addAPI(items) { // Define root api sidebar item const apiItem = { type: 'category', label: 'Vocdoni API', link: { type: 'doc', - id: 'vocdoni-api/vocdoni-api' + id: 'vocdoni-api/vocdoni-api', }, - items: [] - } + items: [], + }; // Get swagger-generated API sidebar items, filter out index doc require('./docs/vocdoni-api/sidebar.js').forEach(item => { if (item?.type !== 'doc' && item?.label !== 'Vocdoni API') { - apiItem.items.push(item) + apiItem.items.push(item); } - }) - items.push(apiItem) - return items + }); + items.push(apiItem); + return items; } -function toTitleCase (str) { - return str.charAt(0).toUpperCase() + str.substr(1).toLowerCase() +function toTitleCase(str) { + return str.charAt(0).toUpperCase() + str.substr(1).toLowerCase(); } -function modifySDKReference (items) { +function modifySDKReference(items) { for (var index1 in items) { if ( items[index1].type == 'category' && items[index1].label == 'Vocdoni SDK' ) { - const SDKCategory = items[index1] + const SDKCategory = items[index1]; for (var index2 in SDKCategory.items) { if ( SDKCategory.items[index2]?.type == 'category' && @@ -75,36 +76,36 @@ function modifySDKReference (items) { label: 'Reference', link: { type: 'doc', - id: 'sdk/reference/sdk-reference' - } - } + id: 'sdk/reference/sdk-reference', + }, + }; // Capitalize category labels for (var index3 in referenceCategory?.items) { if (referenceCategory.items[index3].label != null) { referenceCategory.items[index3].label = toTitleCase( referenceCategory.items[index3].label - ) + ); } } // Sort sidebar items by ID according to sdkSidebarIDOrder referenceCategory.items = referenceCategory.items.sort((i1, i2) => { return ( (sdkSidebarIDOrder[i1.id] || 0) - (sdkSidebarIDOrder[i2.id] || 0) - ) - }) - SDKCategory.items[index2] = referenceCategory + ); + }); + SDKCategory.items[index2] = referenceCategory; } } - items[index1] = SDKCategory + items[index1] = SDKCategory; } } - return items + return items; } -module.exports = async function sidebarItemsGenerator ({ +module.exports = async function sidebarItemsGenerator({ defaultSidebarItemsGenerator, ...args }) { - const sidebarItems = await defaultSidebarItemsGenerator(args) - return modifySDKReference(addAPI(skipAPI(sortItems(sidebarItems)))) -} + const sidebarItems = await defaultSidebarItemsGenerator(args); + return modifySDKReference(sortItems(addAPI(skipAPI(sidebarItems)))); +};