(ONGOING) docs: initiate docs rewrite and theme change #905
Conversation
|
@chaws @mwasilew this just introduces the "rough-ins" for the new docs. I have only written the intro and the model under the 'guide' dir/section for now. I've categorised each doc topic by directory to make things cleaner and easier to handle. There is a theme dependency and markdown processor dependency that will need to be used to generate this. I haven't added them to requirements.txt or requierments-dev.txt. This PR can remain a staging ground until we have rewritten old docs into markdown and put them under their relevant directory then revamps can be incremental. The two deps are: sphinx_rtd_theme and recommonmark. We also may not need files like 'make.bat' so we can remove those during the rewrite. |
There was a problem hiding this comment.
I would very much prefer to use markdown syntax as described here https://www.markdownguide.org/basic-syntax/ and get rid of all rst bits. It's way easier to write/edit markdown than rst.
| @@ -0,0 +1 @@ | |||
| <svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 159.96 37.32"><defs><style>.cls-1{fill:#1d1d1b;}.cls-2{fill:#c30033;opacity:0.6;}</style></defs><title>SQUAD</title><path class="cls-1" d="M58.26,29.91a15.74,15.74,0,0,1-11.07,6.75l-2-15.73Z"/><path class="cls-2" d="M55.88,25.77l-13.09-9,2,15.74a14.78,14.78,0,0,1-2,.14,15.86,15.86,0,1,1,13.09-6.89Z"/><path d="M20.18,7.18a2.39,2.39,0,0,1-.61.72,1.36,1.36,0,0,1-.81.22,2,2,0,0,1-1-.33c-.36-.22-.79-.46-1.27-.72a12.11,12.11,0,0,0-1.68-.72A6.68,6.68,0,0,0,12.58,6,4.85,4.85,0,0,0,9.24,7,3.3,3.3,0,0,0,8.12,9.63a2.43,2.43,0,0,0,.61,1.7,5.44,5.44,0,0,0,1.61,1.17,15.45,15.45,0,0,0,2.26.88c.85.26,1.71.54,2.6.84a22.68,22.68,0,0,1,2.6,1.09,9.22,9.22,0,0,1,2.26,1.57,7.26,7.26,0,0,1,1.61,2.3,8.07,8.07,0,0,1,.61,3.32,10.55,10.55,0,0,1-.74,4,9.51,9.51,0,0,1-2.13,3.24A9.91,9.91,0,0,1,16,31.89a12.72,12.72,0,0,1-4.64.79,14.68,14.68,0,0,1-3-.29,16.9,16.9,0,0,1-2.84-.84A16.14,16.14,0,0,1,3,30.26a11,11,0,0,1-2.1-1.67l1.89-3.05A2,2,0,0,1,3.38,25a1.7,1.7,0,0,1,.81-.22,2.21,2.21,0,0,1,1.23.43c.43.29.92.6,1.48.94a11,11,0,0,0,1.94.94,7.25,7.25,0,0,0,2.65.43,5.31,5.31,0,0,0,3.48-1,3.78,3.78,0,0,0,1.24-3.08,3,3,0,0,0-.61-1.91A5,5,0,0,0,14,20.26a12.28,12.28,0,0,0-2.25-.84c-.85-.24-1.71-.5-2.6-.78a21.48,21.48,0,0,1-2.59-1A8.17,8.17,0,0,1,4.3,16a7.49,7.49,0,0,1-1.6-2.45,9.55,9.55,0,0,1-.61-3.63A8.64,8.64,0,0,1,4.8,3.68a10.11,10.11,0,0,1,3.27-2A12.06,12.06,0,0,1,12.52.87a15.09,15.09,0,0,1,5.2.87,11.75,11.75,0,0,1,4.05,2.42Z"/><path d="M78.57,27.2a7.18,7.18,0,0,0,2.81-.53,5.87,5.87,0,0,0,2.1-1.49,6.67,6.67,0,0,0,1.31-2.34,9.94,9.94,0,0,0,.45-3.09V1.22h6.43V19.75a14.31,14.31,0,0,1-.91,5.2A11.61,11.61,0,0,1,88.15,29,11.81,11.81,0,0,1,84,31.72a16.12,16.12,0,0,1-11,0A12,12,0,0,1,69,29,11.87,11.87,0,0,1,66.35,25a14.31,14.31,0,0,1-.91-5.2V1.22h6.43V19.75a9.94,9.94,0,0,0,.45,3.09,6.67,6.67,0,0,0,1.31,2.34,5.78,5.78,0,0,0,2.1,1.49A7.26,7.26,0,0,0,78.57,27.2Z"/><path d="M126.29,32.34h-5a2.22,2.22,0,0,1-1.36-.39,2.31,2.31,0,0,1-.79-1L117,25h-12.4l-2.1,5.93a2.66,2.66,0,0,1-.75,1,2.09,2.09,0,0,1-1.36.43h-5L107.56,1.22h6.58ZM115.47,20.52,112.1,11c-.2-.51-.41-1.09-.63-1.76s-.43-1.4-.63-2.19c-.2.8-.41,1.54-.64,2.22s-.43,1.27-.63,1.77l-3.34,9.48Z"/><path d="M159.1,16.77A16.81,16.81,0,0,1,158,23,14.49,14.49,0,0,1,154.71,28a14.85,14.85,0,0,1-5,3.21,17.73,17.73,0,0,1-6.53,1.16h-12V1.22h12a17.73,17.73,0,0,1,6.53,1.15,14.75,14.75,0,0,1,5,3.23A14.54,14.54,0,0,1,158,10.52,16.75,16.75,0,0,1,159.1,16.77Zm-6.61,0a14,14,0,0,0-.65-4.4A9.25,9.25,0,0,0,150,9.06,8.09,8.09,0,0,0,147.07,7a9.89,9.89,0,0,0-3.92-.73h-5.49v21h5.49a10.07,10.07,0,0,0,3.92-.72A7.77,7.77,0,0,0,150,24.5a9.25,9.25,0,0,0,1.84-3.31A14.07,14.07,0,0,0,152.49,16.77Z"/></svg> | |||
There was a problem hiding this comment.
does it need a weird number in the file name?
docs/conf.py
Outdated
| source_suffix = ['.txt', '.md'] | ||
|
|
||
| master_doc = 'index' | ||
| copyright = '2016-2020, Linaro Limited' |
There was a problem hiding this comment.
it's repeated from line 24. This one is correct.
docs/guide/install.txt
Outdated
| --------------------- | ||
| SQUAD is a Django application and it is Python3 only. To setup a development environment locally, it can be installed from PyPi using ``pip``: | ||
|
|
||
| ..code-block:: bash |
There was a problem hiding this comment.
does the github syntax work here:
https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code
It's much more 'techwriter friendly' than rst. That's why I asked about changing to markdown.
docs/guide/model.txt
Outdated
| them at the end prepares all the data in a consistent way, and submits | ||
| it to dashboard. | ||
|
|
||
| Input file formats |
There was a problem hiding this comment.
I would prefer hash based headings.
amrohassaan
force-pushed
the
docs_rewrite
branch
from
cb51264 to
702ca4c
Compare
|
@mwasilew rewritten in MD. There is one link that needs to be fixed at the end of model doc and other docs will be pushed soon. |
|
Hey @amrohassaan do you think this PR is close to finish? From reading the comments, it seems you were very close |
Fixes #700 and #702