Restructure documentation#223
Conversation
6285638 to
074fc25
Compare
|
It looks like a good start to me 👍 |
|
@N-Coder Niko, you've showed an interest of having a section regarding the ICS format. I've added a placeholder file (see I'm not very familiar with ICS, but I would be willing to review and comment it if you would like to provide some text. Wanna try? 😉 |
|
I've moved one file into another category ( Of course it is not really finished. As I'm not sure what else I can provide, I think it's time to decide if we want to publish it as the current state and improve it step-by-step, or we want to do some more modifications in this PR. If you like, I can squash the commits into one if you prefer it that way. @C4ptainCrunch what do you like? |
|
I mirrored your branch on this repo (the branch is named Also, as we just released ics.py 0.7, i merged master into (the mirror of) your branch. You might want to pull that into yours :) |
|
It also seems like the reorg broke some links and footnotes. |
|
Small other comment : things like
|
Thanks for the hint, but I get the same warnings in master too. 😉 That's why I assume, It's not caused by my reorganization of the doc.
I can abbreviate it and remove the "with Thunderbird" part. That's easy to fix. However, just as a more general note, it will loose clarity and you can get into the same issue again when having a longer title. IMHO, this is not a documentation issue, but a layout issue. 😉 |
* Remove/rename files: - examples.rst: Use content in quickstart.rst - misc.rst -> explanation/misc.rst * Move files: - api.rst -> reference/api.rst - introduction.rst -> explanation/icalender-format.rst - about.rst -> explanation/about.rst * Add new files: - reference/changelog.rst - howtos/installation.rst, howtos/quickstart.rst - explanation/contributing.rst
There are limitations and howto. Better we separate these; additionally, the titles get more attention
* Rephrase first paragraph a bit * Separate/sort existing documentation into the four types: howtos, tutorials, explanation, and reference * Create new files as necessary * Rename some files to make it visible about the content
* Explain how to check version of Python & pip * Focus on pip * Show how to install ics.py with and without a virtual environment
* Correct title * Use ^ instead of < to avoid lines looking like conflict markers * Amend main title with "... to ics.py" * Use verbs and active voice in some list entries to engage our developers
ccaf32f to
92eb26c
Compare
|
Ok, let's go ! I'm merging this too if it's ok to you then we can iterate again with smaller PR on master :) |
|
@C4ptainCrunch Yes, please do. I agree, we can improve it in other PRs step-by-step. Thanks! 👍 Oh, one question: should I squash all commits? |
This PR is a first draft for issue #220. It contains the following changes:
Marked it as "draft" for the time being as it's not finished and only the skeleton for our future documentation. It's also to make sure the structure is good enough before I move on and add more content.
Some changes may seem radical. I'm sure there are probably better ways how to structure it, but it's a start so we can discuss the pros and cons. I'm sure we can improve it together! 😃
There are still a lot of work to do:
advanced.rstfile. Probably it needs to be rewritten and can be integrated into a tutorial, I'm not sure... 🤔autodoc: failed to import class 'parse.Container' from module 'ics'; the following exception was raised: No module named 'ics.parse'andDuplicate explicit target name: "github thread". I leave that to someone else to fix it. 😉Screenshot (click me to show)
@C4ptainCrunch @N-Coder So what do you think? Could that work as a start? Anything you like/dislike? Let me know! 👍