alda-lang / alda.io Goto Github PK
View Code? Open in Web Editor NEWThe official Alda website
Home Page: https://alda.io
The official Alda website
Home Page: https://alda.io
See #8 for context.
I think the Python documentation is a good source of inspiration. There are some nice features here:
The documentation is available by release version. For example, if you're using Python 3.5 instead of 3.6, you can find the latest 3.5 version (i.e. 3.5.3) docs here.
The landing page has big links to the most relevant information, like the changelog, a tutorial, installation instructions, an FAQ, etc.
As you navigate through the docs, there is a sidebar with quick links to each section, making it easy to zero in on a particular section.
I previously looked into http://readthedocs.io, and it seems like a nice way to set up something like this. I did a quick port of our existing documentation here: http://alda.readthedocs.io/en/latest/
The docs are actually generated from the alda-lang/alda repo, which is great because we can still keep the docs version controlled alongside the source code, and easily generate different versions of the documentation based on Alda release versions.
The next steps are to organize the docs better so that they look good on readthedocs.io, and then we could CNAME the docs to something like http://docs.alda.io and include a link on the website.
See #8 for context.
This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.
The docs should have a page guiding the reader through:
This information is currently all in the README:
https://github.com/alda-lang/alda#installation
https://github.com/alda-lang/alda#midi-soundfonts
https://github.com/alda-lang/alda#editor-plugins
Once we've moved it to the docs, we can replace those parts of the README with a link to the docs.
I think this page could also include some very basic usage examples like what we have here, and then suggest that the reader either read the Alda Command-Line Client docs for more technical information, or proceed to the Tutorial section for a guided tour of Alda.
Moved from alda-lang/alda#50.
You can see our current logo here: https://github.com/alda-lang
It's something I hacked together in GIMP late one night because I was tired of looking at the default org logo generated by GitHub.
What I would love, though, is for someone with better graphic design skills than I to come up with something more pleasing to the eye.
I'm thinking something that doesn't have the word "alda" on it. Maybe some kind of stylized "A"? The name Alda comes from the Quenya word for "tree," so something tree-related might be cool, but that's not a requirement.
A number of possible logos have been proposed in the original issue, but I am still looking for the perfect Alda logo.
By the way, I really appreciate all of the proposed logos so far! I apologize that I'm being so picky about this. Alda is very near & dear to my heart, and my standards about its logo design are high.
Please don't be discouraged if I've passed on your logo so far. ๐
See #8 (comment) for context.
The tutorial sections could be something like:
- Anatomy of an Alda Score (a broad overview of the structure of a score file, explaining instrument parts, variable definitions, etc. without going into too much detail)
- Notes and Rests
- Chords and Voices
- Grouping Instruments (covers instrument groups and naming instruments/groups)
- Attributes
- Advanced Rhythms (covers second/millisecond durations and CRAM notation)
- Using Variables
- Generating Music by Writing Code (covers inline Clojure code and an overview of the alda.lisp DSL)
This is just a quick sketch; I'm definitely open to any suggestions about how to tweak this, but maybe this outline can be a good starting point.
This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.
See #8 for context.
This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.
Quoting myself:
I made a quick sketch of what these sections might look like:
From the landing page, sections could include:
- What's new in Alda 1.0.0? (1.1.0, 1.2.0, etc.)
- Setup and Usage
- Tutorial (see below)
- Reference (would include things like...)
- list of instruments
- list of attributes
- alda.lisp API docs (i.e. a list of functions available in the alda.lisp namespace, what they do and how to use them)
- The Alda Command-Line Client
- Developer Portal (would include information like...)
- Using Alda in a Clojure program
- Technical details about Alda components
- Writing your own Alda components
- ZeroMQ architecture
- Community (links to the Alda Slack group, subreddit, GitHub org, etc. and information about contributing to Alda)
Quoting @abhi18av:
@daveyarwood Let's include the your talk videos in the docs.
Alda: A Music Programming Language, Built in Clojure (David Yarwood)
I think we could also include a "Talks and Demos" section where we could include links to the videos above, as well as this excellent demo by @jimcheetham.
See #8 for context.
This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.
The Alda Developer Portal will be a place for technical details not necessarily relevant to the typical end-user, but useful for developers who want to know how Alda works under the hood.
It should include information about things like:
The syntax highlighting looks a little wonky because, with Alda being a new language, Rouge has no idea how to lex and highlight Alda code.
It seems like it shouldn't be too hard to create an Alda lexer for Rouge.
For reference: https://github.com/jneen/rouge#using-the-lexer-dsl
Alda doesn't yet have an "official" logo -- if/when we do, we should clearly display it on the website ๐
Related: alda-lang/alda#50
See #8 for context.
This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.
Note: no docs currently exist for the Alda CLI client -- this is new territory. I think it would be good to include some practical examples of the Alda command-line workflow using the alda
client, some information about Alda server and worker processes, how to play files or strings of code, how to start the REPL, etc.
Part of #8.
This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.
The way readthedocs.io is set up, documentation versions are automatically mapped to branches of the repo. The latest version in each series of Alda releases (e.g. 1.0.X, 1.1.X, 1.2.X...) will have its own version of the documentation, corresponding to the docs folder in that branch of the alda-lang/alda repo.
I like the way the Python documentation site handles this:
https://docs.python.org/3 (landing page)
https://docs.python.org/3/whatsnew/3.6.html (summary of changes since the last minor version, 3.5)
https://docs.python.org/3.6/whatsnew/changelog.html (detailed changelog for this series of releases)
See #8 for context.
This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.
This section could include links like the ones I listed on my GitHub sponsors page.
Right now alda.io is just a placeholder. We need a decent layout and some basic content, for starters. At the moment, we're getting a lot of mileage out of having all of our info, releases, examples, documentation in the alda-lang/alda GitHub repo, but some of the most pertinent content ought to be made available on alda.io, as well.
Some ideas:
If you're here reading this, please share your thoughts! What would you like to see when you go to Alda's official website?
See #8 for context.
This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.
The Community section should include links to/information about:
From alda-lang/alda#210, cc: @lifeluvr @elyisgreat @jgkamat
Should be a webpage with concise examples, something like the Emmet cheat sheet.
Reference material currently available:
The installation guide's final example command: alda play -c '(tempo! 160) trumpet: (quant 60) f12 b- > d f6 d12 f1'
doesn't work on windows producing "No Alda source code input supplied." error.
Changing the single quotes to regular ones (alda play -c "(tempo! 160) trumpet: (quant 60) f12 b- > d f6 d12 f1"
) does the trick.
Not sure if it happens only for me, but thought it's important to either address this as an "alda on windows" bug, or just fix the doc
See #8 for context.
This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.
The Reference section would include information like:
Continuing the conversation from #1 / #7 (cc: @abhi18av):
Alda's documentation currently lives as a series of unorganized Markdown files in the main Alda repo. My initial thought was that the documentation could be managed in version control alongside the source code, which is compelling.
However, I think it's more important to have helpful, well-organized documentation available on alda.io, with more of a focus on making it easier to find the information you're looking for.
I think the Python documentation is a good source of inspiration. There are some nice features here:
The documentation is available by release version. For example, if you're using Python 3.5 instead of 3.6, you can find the latest 3.5 version (i.e. 3.5.3) docs here.
The landing page has big links to the most relevant information, like the changelog, a tutorial, installation instructions, an FAQ, etc.
As you navigate through the docs, there is a sidebar with quick links to each section, making it easy to zero in on a particular section.
I previously looked into http://readthedocs.io, and it seems like a nice way to set up something like this. I did a quick port of our existing documentation here: http://alda.readthedocs.io/en/latest/
The docs are actually generated from the alda-lang/alda repo, which is great because we can still keep the docs version controlled alongside the source code, and easily generate different versions of the documentation based on Alda release versions.
The next steps are to organize the docs better so that they look good on readthedocs.io, and then we could CNAME the docs to something like http://docs.alda.io and include a link on the website.
See #8 for context.
This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.
Another great idea from @abhi18av:
Also I feel we need to expand on the examples to something more like a gallery.
I think an "Example Scores" section would be nice. We could adapt the example scores in the alda-core repo and come up with a cohesive set of examples that serve as good demos for Alda's features.
The example scores in the alda-core repo are used for automated testing, so many of them are not really the best demos. We should think about which ones to include and possibly about adding additional examples.
EDIT 2024-03-19: updated example scores link
Looks like the website is returning a 404 error when one tries to access the cheat sheet page at https://alda.io/cheat-sheet.
(I just clicked on "Cheat sheet" on the navbar.)
Currently we do not support https://alda.io, only http://alda.io.
We should get an SSL certificate, maybe through https://letsencrypt.org, and figure out how to set it up through GitHub Pages so that we support https too.
Then, we should always redirect http => https.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.