docs: use Ulwazi theme in starter pack v1.4.1#520
docs: use Ulwazi theme in starter pack v1.4.1#520AnneCYH wants to merge 1 commit intocanonical:mainfrom
Conversation
AnneCYH
force-pushed
the
import-ulwazi-theme
branch
4 times, most recently
from
640fda9 to
26b134b
Compare
- Added how-to guide for using Ulwazi theme as python package - Added Ulwazi to spellcheck exclusion list - Added CHANGELOG entry for non-docs changes Signed-off-by: Anne Chew <[email protected]>
AnneCYH
force-pushed
the
import-ulwazi-theme
branch
from
ebb8264 to
44ede55
Compare
AnneCYH
requested review from
SecondSkoll,
akcano,
dwilding,
medubelko,
minaelee,
rkratky and
tang-mm
as code owners
izmalk
left a comment
izmalk
left a comment
There was a problem hiding this comment.
Thank you for creating the guide. I think we can make it much more useful for people by adding some details. See my suggestions. Most of them are non-blocking, but I'd like to highlight the requirements section, which needs more clarity, IMHO.
| Once you've completed the setup, you are ready to build your documentation site. | ||
|
|
||
| ```{code-block} | ||
| make clean |
There was a problem hiding this comment.
Suggestion: Let's add cd docs here. We need to navigate to the docs directory or whatever the root of the documentation is.
| ulwazi==0.2 | ||
| sphinx-basic-ng | ||
|
|
||
| [...] |
There was a problem hiding this comment.
Suggestion: this three-dots block seems very confusing to me. Let's just list all the requirements for the Ulwazi and provide instructions to add the missing ones to your requirements.txt file after you delete the canonical-sphinx.
Also, we need a note that removing the canonical-sphinx might mean some necessary requirements for your docs might go missing and will need to be added manually later. Ideally, provide a link to the full list of extensions added by canonical-sphinx.
| --- | ||
| myst: | ||
| substitutions: | ||
| ulwazi_zip: "{file}`ulwazi-0.1.tar.gz`" |
There was a problem hiding this comment.
Suggestion: Do we need it at all? I don't see it being used. But if yes, then the latest version now is 0.2. Let's update it here or make it version-agnostic.
| ulwazi_zip: "{file}`ulwazi-0.1.tar.gz`" | |
| ulwazi_zip: "{file}`ulwazi-0.2.tar.gz`" |
| customise-pdf | ||
| migrate-from-pre-extension | ||
| update | ||
| Use Ulwazi theme <use-ulwazi-theme> |
There was a problem hiding this comment.
Suggestion: Since it's experimental, let's not encourage people to actually use it in production for now.
| Use Ulwazi theme <use-ulwazi-theme> | |
| Try Ulwazi theme <use-ulwazi-theme> |
| make clean | ||
| make run | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Suggestion: Can we add a couple of sentences on opening it in the web browser and checking the pages manually for correct rendering with a mandatory request to document all issues and feature requests to the GitHub repo - https://github.com/canonical/ulwazi/issues/new
|
|
||
| % LINKS | ||
|
|
||
| [Ulwazi theme]: https://pypi.org/project/ulwazi/0.2/ |
There was a problem hiding this comment.
Suggestion: let's remove 0.2 at the end from the link so it will link to the package and show the latest version.
| # TODO: Update with the official name of your project or product | ||
|
|
||
| project = "Documentation starter pack" | ||
| project = "Documentation starter pack with Ulwazi" |
There was a problem hiding this comment.
Suggestion: Too long text here looks funny in the Nav Menu
| project = "Documentation starter pack with Ulwazi" | |
| project = "Documentation with Ulwazi" |
|
|
||
| Update the project configuration in {file}`conf.py`: | ||
|
|
||
| - Add the "version" setting |
There was a problem hiding this comment.
Suggestion: I find it not very helpful to have this list or the code snippets below.
Let's put some examples of the commits adapting the file for the Ulwazi instead? It will show a proper diff in a much more readable format. For example: Kafka test deployment commit.
|
@AnneCYH Have you had a chance to look at Vlad's comments? I'll take a look once they're resolved. |
3 participants
CHANGELOG.mdwith relevant non-documentation file changes?