Where to put images for README.md, FAQ.md, CONTRIBUTING.md and other docs in our Github repo?
To fix an issue I want to add a screen shot to our FAQ.md. Into which folder shall I put the screen shot file in our Github repo? I would suggest one of these names as new folder under root - assets - images - pics - res(ources) What are your proposals? PS: Moving all *.md into a separate repo would also work (to separate code from docs) but requires more work to do I guess (move files + add and change links)
I don't think having more repositories will make things simpler. I propose the following - /doc -> for .md files except README.md - /doc/assets -> for anything and everything attached to the .md files (images, document specific example files, etc.). Cheers, H. On 13.05.2024 ÖS 2:58, BiT dev wrote:
To fix an issue I want to add a screen shot to our FAQ.md.
Into which folder shall I put the screen shot file in our Github repo?
I would suggest one of these names as new folder under root
- assets - images - pics - res(ources)
What are your proposals?
PS: Moving all *.md into a separate repo would also work (to separate code from docs) but requires more work to do I guess (move files + add and change links) _______________________________________________ Bit-dev mailing list -- bit-dev@python.org To unsubscribe send an email to bit-dev-leave@python.org https://mail.python.org/mailman3/lists/bit-dev.python.org/ Member address: hakan@bayindir.org
THX a lot Hakan, this sounds perfect for my requirements. @rest of the world ;-) Any objections/proposals? On Mon, 2024-05-13 at 16:03 +0300, Hakan Bayındır wrote:
I don't think having more repositories will make things simpler.
I propose the following - /doc -> for .md files except README.md - /doc/assets -> for anything and everything attached to the .md files (images, document specific example files, etc.).
Cheers,
H.
On 13.05.2024 ÖS 2:58, BiT dev wrote:
To fix an issue I want to add a screen shot to our FAQ.md.
Into which folder shall I put the screen shot file in our Github repo?
I would suggest one of these names as new folder under root
- assets - images - pics - res(ources)
What are your proposals?
PS: Moving all *.md into a separate repo would also work (to separate code from docs) but requires more work to do I guess (move files + add and change links) _______________________________________________ Bit-dev mailing list -- bit-dev@python.org To unsubscribe send an email to bit-dev-leave@python.org https://mail.python.org/mailman3/lists/bit-dev.python.org/ Member address: hakan@bayindir.org
Hello Am 13.05.2024 15:03 schrieb Hakan Bayındır:
I don't think having more repositories will make things simpler.
I do think the same. Am 13.05.2024 15:03 schrieb Hakan Bayındır:
I propose the following - /doc -> for .md files except README.md - /doc/assets -> for anything and everything attached to the .md files (images, document specific example files, etc.).
Sounds perfect to me. I also do have in mind to migrate our reference documentation (currently in "common/doc-dev"), the user manual (in a separate repo "bit-team/doc") and our "developers documentation " (also in "common/doc-dev") into our primary repository. In this case a root folder "doc" or "docs" would be perfect. Because of that now creating a "doc" folder is a good step into the future. ;) Best Christian
I propose the following - /doc -> for .md files except README.md - /doc/assets -> for anything and everything attached to the .md files (images, document specific example files, etc.).
OK, could we "take a break" after having merged all open documentation-related PRs to then prepare a PR that just moves everything (with or better still without our reference doc) into the new folder structure? I would like to prepare a PR then for the Synology FAQ changes where I need to add screen shots and don't want to merge this structure change into one PR: https://github.com/bit-team/backintime/issues/1674 On Mon, 2024-05-13 at 13:18 +0000, c.buhtz@posteo.jp wrote:
Hello
Am 13.05.2024 15:03 schrieb Hakan Bayındır:
I don't think having more repositories will make things simpler.
I do think the same.
Am 13.05.2024 15:03 schrieb Hakan Bayındır:
I propose the following - /doc -> for .md files except README.md - /doc/assets -> for anything and everything attached to the .md files (images, document specific example files, etc.).
Sounds perfect to me.
I also do have in mind to migrate our reference documentation (currently in "common/doc-dev"), the user manual (in a separate repo "bit-team/doc") and our "developers documentation " (also in "common/doc-dev") into our primary repository. In this case a root folder "doc" or "docs" would be perfect. Because of that now creating a "doc" folder is a good step into the future. ;)
Best Christian _______________________________________________ Bit-dev mailing list -- bit-dev@python.org To unsubscribe send an email to bit-dev-leave@python.org https://mail.python.org/mailman3/lists/bit-dev.python.org/ Member address: python@altfeld-im.de
Am 14.05.2024 21:16 schrieb BiT dev:
OK, could we "take a break" after having merged all open documentation-related PRs to then prepare a PR that just moves everything (with or better still without our reference doc) into the new folder structure?
I wouldn't make it such a one-big-job thing. Just move in there what you need for your Synology FAQ entry. The rest will come later. I wouldn't touch and relocate the "reference doc" and its Sphinx setup until we migrated to a modern Python Packaging Standard. Currently the Sphinx setup is very fragil because it depends on its location relative to the py files in the repo. With correct packaging the location (sys.path etc) is not relevant anymore. But you know the packaging migration is a big deal and won't happen in the next month's.
I would like to prepare a PR then for the Synology FAQ changes where I need to add screen shots and don't want to merge this structure change into one PR:
Maybe I don't see the big picture but I don't see a big structure change. Don't you just move your screenshots into "doc/assests/*" and modifying the FAQ.md file? Best, Christian
On Tue, 2024-05-14 at 20:44 +0000, c.buhtz@posteo.jp wrote:
Am 14.05.2024 21:16 schrieb BiT dev:
OK, could we "take a break" after having merged all open documentation-related PRs to then prepare a PR that just moves everything (with or better still without our reference doc) into the new folder structure?
I wouldn't make it such a one-big-job thing. Just move in there what you need for your Synology FAQ entry.
I'll do so, that is the easy part (new content).
I would like to prepare a PR then for the Synology FAQ changes where I need to add screen shots and don't want to merge this structure change into one PR:
Maybe I don't see the big picture but I don't see a big structure change. Don't you just move your screenshots into "doc/assests/*" and modifying the FAQ.md file?
I plan to move the FAQ.md and perhaps also the Contributing.md into /doc and just want to avoid merge conflicts with open PRs Then I will modify the FAQ.md (in the same PR or in a new one)
Am 15.05.2024 00:27 schrieb BiT dev:
I plan to move the FAQ.md and perhaps also the Contributing.md into /doc and just want to avoid merge conflicts with open PRs
Mhm... To my experience files like CONTRIBUTING and README always stay in a repos root directory and users do expect it that way. I also would treat FAQ.md the same. But I don't veto this. I can also live with having that files in a sub-folder. About moving the files. I experimented with that and can say that git can track this without problems. You just have to move the files with "git mv" instead just "mv".
participants (3)
-
BiT dev -
c.buhtz＠posteo.jp -
Hakan Bayındır